#git #cli

app gfold

CLI tool to help keep track of your Git repositories

38 releases (17 stable)

Uses new Rust 2021

4.0.0 May 10, 2022
4.0.0-rc.1 Mar 13, 2022
3.1.0-rc.2 Feb 12, 2022
3.0.0-rc.3 Dec 29, 2021
0.8.0 Nov 26, 2020

#8 in Command line utilities

Download history 17/week @ 2022-01-30 27/week @ 2022-02-06 19/week @ 2022-02-13 43/week @ 2022-02-20 14/week @ 2022-02-27 2/week @ 2022-03-06 140/week @ 2022-03-13 110/week @ 2022-03-20 16/week @ 2022-03-27 18/week @ 2022-04-03 15/week @ 2022-04-10 43/week @ 2022-04-17 109/week @ 2022-04-24 178/week @ 2022-05-01 220/week @ 2022-05-08 664/week @ 2022-05-15

1,193 downloads per month

Apache-2.0

51KB
896 lines

gfold

latest release tag crates.io version license build status bors enabled

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
another-day     unclean   main     git@github.com:motm3/another-day.git
beautiful-trip  bare      dev      none
damaged         unpushed  dev      https://github.com/motm3/damaged.git
dive            unclean   patch    git@github.com:motm3/dive.git
solo-dolo       clean     main     https://github.com/motm3/solo-dolo.git
tpm             clean     issue15  git@github.com:motm3/the-pale-moonlight.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. 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:

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 -i flag.

gfold -i

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

Packaging status

Homebrew Install (macOS only)

You can use Homebrew to install the tap.

brew install nickgerace/nickgerace/gfold

Note: the tap may not work with Linuxbrew.

Arch Linux

arch linux

You can use pacman to install gfold from the community repository.

pacman -S gfold

Nix and NixOS

You can install gfold from nixpkgs:

nix-env --install gfold

Cargo Install

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

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.

Downloading and Installing the Binary

If you would prefer to use a convenience script over downloading directly from the aforementioned releases page, we have one! You can execute the installation helper script on a compatible system with bash installed (e.g. macOS and Linux).

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.

Uninstalling the Downloaded Binary

To uninstall gfold fully after using the above 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.

Build From Source Locally

If you want to install from source locally, 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
)

Preferred Installation Method 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.

Name Type Description
Arch Linux community repository packaging the gfold package (note: before moving to the community repository, the AUR was previously used for distribution)
"One Hundred Rust Binaries" article featured gfold
nixpkgs packaging the gfold package
nvim-gfold.lua project a neovim plugin for gfold (announcement Reddit post)

Dependencies

~18MB
~411K SLoC