gfold

This README is for gfold 3.x users. Since gfold 3.x has not yet been released, contents of this README may be inapplicable to your version of gfold.

For the latest, full release of gfold 2.x, please refer to the README corresponding to the latest, full release.

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

The classic display mode can be toggled on with --classic.

% gfold --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).

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. However, if you would like to target another directory, you can pass that path (relative or absolute) as the first argument or change the default path in the config file.

Installation

There are multiple methods for installing gfold.

Homebrew (macOS only)

You can use Homebrew to install the tap.

brew install nickgerace/nickgerace/gfold

Please note: the tap may not work with Linuxbrew.

AUR

You can use a Linux distribution that supports installing packages from the AUR, Arch User Respository, to install the following:

• gfold: builds from source
• gfold-git: development package

Many people choose to use an AUR helper, such as paru, in order to install their AUR packages.

paru -S gfold

Cargo (recommended)

You can use cargo to install the crate on almost any platform.

cargo install --locked gfold

Keeping the crate up to date is easy with cargo-update.

cargo install --locked cargo-update
cargo install-update -a

Binary from a Release

If you do not want to use one of the above installation methods, you can download a binary from the releases page.

curl https://raw.githubusercontent.com/nickgerace/gfold/main/scripts/install.sh | bash

To uninstall gfold fully, after using this installation method, execute the following script:

curl 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.

Security Considerations

Please note that the installation convenience script does not verify the binary with a checksum. Discretion is advised, including downloading and reading the script before execution.

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/gfold.json

On Windows, the config file is located at the following path:

{FOLDERID_Profile}\.config\gfold\gfold.json

Creating and using the config file is entirely optional, and you can ignore your config file at any time using the -i flag.

Example: Creating a Config File

Here is an example creation workflow for a config file. This config file will default to the classic display mode and set the default path to $HOME, rather than the current working directory.

gfold --classic ~/ --print > $HOME/.config/gfold/gfold.json

Here are the contents of the resulting config file:

{
  "path": "/home/neloth",
  "display_mode": "Classic"
}

Example: Backing Up a Config file

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.json $HOME/.config/gfold/gfold.json

Now, you can update the config file within your repository and include the linking as part of your environment setup workflow.

Compatibility

gfold is intended to be ran on any tier one Rust 🦀 target that git is also available on. Please file an issue if your platform is unsupported.

Troubleshooting

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