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).
All releases now follow the CalVer versioning scheme, starting with 2025.2.1.
This change is both forwards and backwards compatible with the Semantic Versioning versioning scheme, which was used from the first release through version 4.6.0.
No end user action is required specifically for the versioning scheme change itself.
This announcement will be eventually removed from this README and will eventually be moved into the CHANGELOG.
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.
By default, 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.
After traversal, gfold leverages rayon to perform concurrent, read-only analysis of all Git repositories detected.
Analysis is performed by leveraging the git2-rs library.
Provide the -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.
gfold
# Operate in the parent directory.
gfold ..
# Operate in the home directory (first method).
gfold $HOME
# Operate in the home directory (second method).
gfold ~/
# Operate with an absolute path.
gfold /this/is/an/absolute/path
# Operate with a relative path.
gfold ../../this/is/a/relative/path
# Operate with three paths.
gfold ~/src ~/projects ~/codeIf 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?
Upon execution, gfold will look for a config file at the following paths (in order):
$XDG_CONFIG_HOME/gfold.toml$XDG_CONFIG_HOME/gfold/config.toml$HOME/.config/gfold.toml
$XDG_CONFIG_HOME refers to the literal XDG_CONFIG_HOME environment variable, but will default to the appropriate operating system-specific path if not set (see user_dirs for more information).
If a config file is found, gfold will read it and use the options specified within.
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.tomlHere are the contents of the resulting config file:
paths = ['/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 -i flag.
gfold -iYou can restore the config file to its defaults by using the same flag.
gfold -i > $HOME/.config/gfold.tomlIn 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.tomlYou can back up a config file and track its history with git.
On macOS, Linux, and most systems, you can link the file back to a git repository.
ln -s <path-to-repository>/gfold.toml $HOME/.config/gfold.tomlNow, 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 using the core formulae.
However, you may run into a naming collision on macOS if coreutils is installed via brew.
See the troubleshooting section for a workaround and more information.
brew install gfoldYou can use pacman to install gfold from the extra repository.
pacman -S gfoldYou can install gfold from nixpkgs:
nix-env --install gfoldIf you are using flakes, you can install using the nix command directly.
nix profile install "nixpkgs#gfold"You can use cargo to install the crate on almost any platform.
cargo install gfoldUse the --locked flag if you'd like Cargo to use Cargo.lock.
cargo install --locked gfoldKeeping the crate up to date is easy with cargo-update.
cargo install cargo-update
cargo install-update -aIf 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.
If you would like an example on how to build from source, refer to the manual install guide.
The tap located at nickgerace/homebrew-nickgerace has been deprecated. Please use the aforementioned core Homebrew package instead.
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.
If you encounter unexpected behavior or a bug and would like to see more details, please run with increased verbosity.
gfold -vvvIf the issue persists, please file an issue. Please attach relevant logs from execution with sensitive bits redacted in order to help resolve your issue.
If fold from GNU Coreutils is installed on macOS via brew, it will be named gfold.
You can avoid this collision with shell aliases, shell functions, and/or PATH changes.
Here is an example with the o dropped from gfold:
alias gfld=$HOME/.cargo/bin/gfoldFor more information and thanks to users and the "community" at large, please refer to the COMMUNITY THANKS file.
- Packages for NixOS, Arch Linux and more
- "One Hundred Rust Binaries", an article that featured
gfold - nvim-gfold.lua, a
neovimplugin forgfold(announcement Reddit post)