gfold
This README is for users building from
main
in anticipation ofgfold 4.0.0
. Sincegfold 4.0.0
has not yet been released, contents of this README may be inapplicable to your version ofgfold
.For the latest, full release (
gfold 3.0.0
), please refer to the README most closely corresponding to it (92e976b207
).
gfold
is a CLI-driven application that helps you keep track of multiple Git repositories.
% gfold
astrid ~ /home/neloth/src/astrid
unclean (main)
git@github.com:db/astrid.git
neloth@housetelvanni.dev
fev ~ /home/neloth/src/fev
bare (issue2277)
none
neloth@housetelvanni.dev
gb ~ /home/neloth/src/gb
unpushed (dev)
https://github.com/hrothgar/gb.git
neloth@housetelvanni.dev
pam ~ /home/neloth/src/pam
clean (main)
https://github.com/onc/pam.git
neloth@solstheimcommunityserver.org
Want the classic display mode?
Use -d classic
.
% gfold -d classic
astrid unclean main git@github.com:db/astrid.git
fev bare main none
gb unpushed dev https://github.com/hrothgar/gb.git
neloth unclean patch git@github.com:telvanni/neloth.git
pam clean main https://github.com/onc/pam.git
prime clean issue2287 git@github.com:bos/prime.git
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).
Upcoming Release
The next version of gfold
will be gfold 4.0.0
.
While it might seem odd to bump the major version field so soon, user feedback and feature requests have been front and center for the next release, and setting up gfold
for the future requires bumping that field.
This README reflects changes in between the latest release (gfold 3.0.0
) and the next release (gfold 4.0.0
).
Description
This app displays relevant information for multiple Git repositories in one to many directories. 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.
Usage
Pass in --help
flag to see all the options for using this application.
gfold
gfold ..
gfold $HOME
gfold ~/
gfold /this/is/an/absolute/path
gfold ../../this/is/a/relative/path
Config File
Upon execution, gfold
will look for a config file at the following path on macOS, Linux and similar operating systems:
$HOME/.config/gfold.toml
On Windows, the lookup path will be in a similar location.
{FOLDERID_Profile}\.config\gfold.toml
Creating and using the config file is entirely optional.
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:
= '/home/neloth'
= 'Classic'
= 'Never'
Let's say you created a config file, but wish 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 -i
You 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.toml
Now, you can update the config file within your repository and include the linking as part of your environment setup workflow.
Installation
macOS users: you can use Homebrew to install the tap.
brew install nickgerace/nickgerace/gfold
Note: the tap may not work with Linuxbrew.
Arch Linux users: you can use pacman to install gfold
from the community repository.
pacman -S gfold
If you'd like the development (VCS) package, you can install it from the AUR.
paru -S gfold-git
Note: the above example uses paru, which is an AUR helper used to install packages from the AUR.
Nix and NixOS users: you can install gfold
from nixpkgs:
nix-env --install ripgrep
Rust developers and Cargo users: you can use cargo to install the crate on almost any platform.
cargo install gfold
Keeping the crate up to date is easy with cargo-update.
cargo install cargo-update
cargo install-update -a
Build and install from source: if you want to install from source, and not from crates.io, you can clone the repository and build gfold
.
(
git clone https://github.com/nickgerace/gfold.git
cargo install --locked --path gfold
)
Download a binary: if you do not want to use one of the above installation methods, you can download a binary from the releases page.
curl -s https://raw.githubusercontent.com/nickgerace/gfold/main/scripts/install.sh | bash
Note: the installation convenience script does not verify the binary with a checksum. Discretion is advised, including downloading and reading the script before execution.
To uninstall gfold
fully, after using this installation method, execute the following script:
curl -s https://raw.githubusercontent.com/nickgerace/gfold/main/scripts/uninstall.sh | bash
The uninstall script can also be used for cleanup in the event of a failed install.
Preferred package manager not listed: please file an issue!
Compatibility
gfold
is intended to be ran on any tier one Rust 🦀 target.
Please file an issue if your platform is unsupported.
Troubleshooting
If you encounter unexpected behavior or a bug, please file an issue and debug
locally with RUST_BACKTRACE=1 RUST_LOG=debug
prepended when executing gfold
.
You can also adjust each variable, as needed, to aid investigation.
Please attach relevant logs from execution with sensitive bits redacted in order to help resolve your issue.
Coreutils Collision on macOS
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/gfold
Community
For more information and thanks to contributors, users, and the "community" at large, please refer to the THANKS file.
Projects
- nvim-gfold.lua, a
neovim
plugin forgfold
(announcement Reddit post)
Articles
- "One Hundred Rust Binaries", which featured
gfold
Packaging
- Arch Linux community repository for the
gfold
package - nixpkgs for the
gfold
package - AUR for the
gfold-git
(VCS/development) package- In the past, this included the
gfold
andgfold-bin
packages as well, they those have been deprecated in favor of the official community repository package above
- In the past, this included the