Introduction

mchdir is a command-line tool written in Rust that allows you to create a new directory and immediately change into it. It includes shell integration that defines an a couple of helpful commands in your shell, simplifying directory creation and navigation.

Description

mchdir provides a convenient way to create a new directory and change into it in a single command. While similar functionality can be achieved with a shell script, this project serves as a demonstration of how to create a command-line tool in Rust with shell integration. Additionally, mchdir includes the mct command to create and enter directories in the system's temporary folder.

Why?

I was getting tired of creating a new directory and then changing into it with two separate commands. I wanted a single command that could do both. I wrote a utility to do this decades ago on Windows, and I wanted the same functionality on Linux/macOS.

It's true that you can do the same thing with a simple shell function or alias! However, this project is a demonstration of how to create a command-line tool in Rust that provides shell integration. It will also probably get more features in the future.

Why the need for shell integration too?

It is impossible to change the current working directory of the parent process from a child process (i.e., a command). This is because each process has its own working directory, and changes to the working directory are not propagated to the parent process. Hence, the mcd command cannot change the working directory of the shell that runs it without shell integration.

Features

Create a new directory and change into it with a single command (mcd).
Create a new directory in the system temporary directory and change into it with the mct command.
Change back to the last directory with the mcl command.
Shell integration for bash, zsh, and fish shells as first-class citizens, though it should work in most POSIX-compliant shells too.
Supports automatic installation of shell integration scripts.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Installation

In the future, there will be pre-built binaries available for download, but for now you can use crates.io, build it from source, or install it directly from GitHub.

Prerequisites

Rust programming language (for building from source)
cargo package manager
Linux or macOS (Windows is not supported)

Install from Crates.io

You can install the mchdir command from the crates.io registry using the following command:

cargo install mchdir

Build from Source

Clone the repository:

git clone https://github.com/seapagan/mchdir.git
cd mchdir

Build the project:

cargo build --release

This will produce an executable in the target/release directory.

Install the Executable:

Copy the executable to a directory in your $PATH, for example:

sudo cp target/release/mchdir /usr/local/bin/

Install from GitHub

You can also install the mchdir command directly from GitHub using the following command:

cargo install --git https://github.com/seapagan/mchdir.git

Once installed, you need to enable shell integration to use the mcd and mct commands. See the Shell Integration documentation (next) for more information.

Shell Integration

To enable the mcd, mcl and mct commands in your shell, you need to integrate mchdir with your shell configuration.

Automatic Installation

You can automatically install the shell integration by running:

mchdir install

This command will detect your shell and append the necessary integration code to the bottom of your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish). If it detects that the integration code is already present, it will not add it again.

Manually Add the Integration Code

If automatic installation does not work for your shell, you can manually add the integration code to your shell configuration file.

Bash, Zsh (and other Bash-Like Shells)

Add the following code to your shell's configuration file:

eval "$(mchdir init)"

Fish Shell

Add the following code to your ~/.config/fish/config.fish file:

eval (mchdir init)

Note that after shell integration, you should no longer need to run the mchdir command again, unless you need to reinstall the shell integration. It DOES need to remain in your PATH for the shell integration to work however.

Usage

After installing mchdir, use the following commands:

`mcd` Command

Create a new directory and change into it:
```
mcd my_new_directory
```
Change to the home directory (when no argument is provided):
```
mcd
```
Display help for the mcd command:
```
mcd --help
```

`mct` Command

Create a new directory in the system temporary directory and change into it:
```
mct my_temp_directory
```
Create a truly random directory in the system temporary directory and change into it:
```
mct
```
Display help for the mct command:
```
mct --help
```

`mcl` Command

Changes to the previous directory the shell was in:
```
mcl
```
Display help for the mcl command:
```
mcl --help
```

`mchdir` Command

The mchdir command supports the following subcommands:

Display the shell integration code:
```
mchdir init
```
Install the shell integration automatically:
```
mchdir install
```

License

The MIT License (MIT)
Copyright (c) 2024 Grant Ramsay

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.

Mchdir Documentation