Grit

Grit is a tool for managing local clones of Git (and other) repositories from your terminal.

It allows quickly cloning repositories and switching the current directory to local clones based on a (partial) repository name, with shell auto-completion.

Grit integrates with cloud services such as GitHub and can also be configured to work with self-hosted version control systems.

NOTE: This repository contains Grit version 2 which is under active development and is by no means ready for use. Grit version 1 is available at jmalloc/grit.

Everything below this point in the README is likely not yet functional or subject to change.

---

TODO: asciinema recording of "clone", "go" and "cd" commands

Installation

TODO: use [n]fpm to publish more "acceptable" linux packages

Install via Homebrew

Grit can be installed via Homebrew on macOS or Linux by running the commands below:

brew tap gritcli/grit
brew install grit

Alternatively, install using Homebrew Bundle by adding the following lines to your Brewfile:

tap "gritcli/grit"
brew "grit"

Install manually

1. Download the Grit archive for your platform from the latest release.
2. Launch the gritd in the background when your system starts
3. Put the grit (cli) executable in your path

The gritd daemon is designed to be run as your regular system user; it does not require elevated privileges.

Getting started

TODO

Concepts

For historical reasons (and to avoid overly abstract language) Grit largely uses Git's terminology for version control concepts. For example, a local working copy of a repository is referred to as a "clone".

Source

A source is some remote system that hosts VCS repositories that can be cloned by Grit.

Grit can be configured to consume from any number of sources. Each source uses a specific source driver to communicate with the remote system.

Each source is identified by a unique name. There are several built-in sources:

• bitbucket for repositories hosted on BitBucket Cloud
• github for repositories hosted on GitHub.com
• gitlab for repositories hosted on GitLab.com

Additionally, user-defined sources can be configured to consume repositories from self-hosted VCS systems.

Source Driver

A source driver integrates Grit with a specific kind of source. It encapsulates all of the communication with the remote source, such as API calls and VCS operations.

Grit ships with several built-in source drivers:

• bitbucket for BitBucket Cloud, BitBucket Server and BitBucket Data Center
• gitea for Gitea
• github for GitHub.com and GitHub Enterprise Server
• gitlab for GitLab.com and Self-managed GitLab
• gogs for Gogs

Additionally, custom drivers can be implemented as plugins. There is no requirement that a source driver use Git as its underlying VCS.

VCS Driver

A VCS driver provides low-level integration with version control systems. Each VCS driver can be used by multiple sources; for example, the built-in git VCS driver is used by, among others, the github and bitbucket source drivers.

Configuration

Grit works out-of-the-box with zero configuration, however custom sources and more powerful features can be enabled with some configuration.

Grit configuration files are written in HCL. Grit loads all .hcl files in the ~/.config/grit directory by default. Files that begin with an underscore or dot are ignored.

TODO: provide a guide for things that the user will most likely want to configure:

- Authentication
- Custom sources

The config-reference.hcl file demonstrates all of the available configuration options and their default values.

Migrating from Grit version 1

TODO

History and rationale

I spend most of my day working with Git. Many of the repositories are hosted on GitHub.com, but many more are in my employer's private GitHub Enterprise and BitBucket installations.

Keeping track of hundreds of clones can be a little tedious, so some time back I adopted a basic directory naming convention and wrote some shell scripts to handle cloning in a consistent way.

This worked well for a while, until the list of places I needed to clone from increased further, and I started working more heavily in Go, which, at the time, placed it's own requirements on the location of your Git clones.

Grit is the logical evolution of those original scripts into a standalone project that clones from multiple Git sources.

Grit v1 was hacked together, there were no tests, and there are other more general solutions for navigating your filesystem; but it worked for me and my colleagues.

Grit v2 is an attempt to address some of the feature requests from my colleagues and to make Grit a more pleasant project to maintain, with better internal abstractions, good test coverage and an eye towards extensibility.