49 releases (28 stable)
|Dec 24, 2023
|Jun 26, 2023
|Apr 8, 2023
|Mar 10, 2023
|Nov 26, 2020
#36 in Command line utilities
1,435 downloads per month
gfold is a CLI tool that helps you keep track of multiple Git repositories.
If you'd prefer to use the classic display mode by default, and avoid setting the flag every time, you can set it in the config file (see Usage section).
This app displays relevant information for multiple Git repositories in one to many directories. It only reads from the filesystem and will never write to it. While this tool might seem limited in scope and purpose, that is by design.
gfold looks at every Git repository via traversal from the current working directory.
If you would like to target another directory, you can pass its path (relative or absolute) as the first argument or change the default path in the config file.
-h/--help flag to see all the options for using this application.
# Operate in the current working directory or in the location provided by a config file, if one exists.
# Operate in the parent directory.
# Operate in the home directory (first method).
# Operate in the home directory (second method).
# Operate with an absolute path.
# Operate with a relative path.
If you find yourself providing the same arguments frequently, you can create and use a config file.
gfold does not come with a config file by default and config files are entirely optional.
How does it work?
gfold will look for a config file at the following path on macOS, Linux and similar operating systems.
On Windows, the lookup path will be in a similar location.
For config file creation, you can use the
--dry-run flag to print valid TOML.
Here is an example config file creation workflow on macOS, Linux and similar platforms:
gfold -d classic -c never ~/ --dry-run > $HOME/.config/gfold.toml
Here are the contents of the resulting config file:
path = '/home/neloth'
display_mode = 'Classic'
color_mode = 'Never'
Let's say you created a config file, but wanted to execute
gfold with entirely different settings and you want to ensure that
you do not accidentally inherit options from the config file.
In that scenario you can ignore your config file by using the
You can restore the config file to its defaults by using the same flag.
gfold -i > $HOME/.config/gfold.toml
In addition, you can ignore the existing config file, configure specific options, and use defaults for unspecified options all at once. Here is an example where we want to use the classic display mode and override all other settings with their default values:
gfold -i -d classic > $HOME/.config/gfold.toml
You can back up a config file and track its history with
On macOS, Linux, and most systems, you can link the file back to a
ln -s <path-to-repository>/gfold.toml $HOME/.config/gfold.toml
Now, you can update the config file within your repository and include the linking as part of your environment setup workflow.
You can use Homebrew to install
gfold with a choice of two methods.
Core (macOS and Linux)
gfold is now available in the core formulae!
However, you may run into a naming collision on macOS if coreutils is installed via
See the troubleshooting section for a workaround and more information.
brew install gfold
Tap (macOS only)
The tap is still available if you would like to use it. This is subject to change.
brew install nickgerace/nickgerace/gfold
pacman -S gfold
Nix and NixOS
You can install
gfold from nixpkgs:
nix-env --install gfold
If you are using flakes, you can install using the
nix command directly.
nix profile install "nixpkgs#gfold"
cargo install gfold
--locked flag if you'd like Cargo to use
cargo install --locked gfold
Keeping the crate up to date is easy with cargo-update.
cargo install cargo-update
cargo install-update -a
Download a Binary
If you do not want to use one of the above installation methods and do not want to clone the repository, you can download a binary from the releases page. For an example on how to do that, refer to the manual install guide.
Build From Source
If you would like an example on how to build from source, refer to the manual install guide.
Preferred Installation Method Not Listed?
Please file an issue!
gfold is intended to be ran on any tier one Rust 🦀 target.
Please file an issue if your platform is unsupported.
Usage as a Library
There are two ways to use
gfold as a "library".
- Use the
libgfoldcrate that powers
- Consume valid JSON results from
gfold -d json(not a library, but useful for non-Rust applications)
Troubleshooting and Known Issues
If you encounter unexpected behavior or a bug and would like to see more details, please run
gfold with the following
# You may also want to add relevant arg(s) and flag(s).
RUST_BACKTRACE=1 RUST_LOG=debug gfold
If the issue persists, please file an issue.
Tuning Environment Variables
RUST_LOG do not have
gfold-specific behaviors, you can adjust
them just as you would in other projects to aid investigation.
Please attach relevant logs from execution with sensitive bits redacted in order to help resolve your issue.
Coreutils Collision on macOS
fold from GNU Coreutils is installed on macOS via
brew, it will be named
You can avoid this collision with shell aliases, shell functions, and/or
Here is an example with the
o dropped from
If you are seeing
unsupported extension name extensions.worktreeconfig or similar errors, it may be related to
This repository's tracking issue is #205.
For more information and thanks to contributors, users, and the "community" at large, please refer to the THANKS file.