grit package - github.com/gritcli/grit

README ¶

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

Download the Grit archive for your platform from the latest release.
Launch the gritd in the background when your system starts
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.

Documentation ¶

Overview ¶

Package grit is a CLI tool (and accompanying agent daemon) for keeping track of (and quickly switching between) many local clones of remote source repositories.

Source Files ¶

View all Source files

doc.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api Package api contains the definition for the gRPC services that the CLI uses to communicate with the daemon.	Package api contains the definition for the gRPC services that the CLI uses to communicate with the daemon.
cli Package cli is the entry-point for the Grit CLI executable.	Package cli is the entry-point for the Grit CLI executable.
internal/apitea Package apitea contains bubbletea messages and commands for integrating bubbletea programs with the Grit API.	Package apitea contains bubbletea messages and commands for integrating bubbletea programs with the Grit API.
internal/commands Package commands contains the root CLI command.	Package commands contains the root CLI command.
internal/commands/clone Package clone contains the implementation of the "clone" command.	Package clone contains the implementation of the "clone" command.
internal/commands/setupshell Package setupshell contains the implementation of the "setup-shell" command.	Package setupshell contains the implementation of the "setup-shell" command.
internal/commands/source Package source contains the implementation of the "source" command.	Package source contains the implementation of the "source" command.
internal/commands/source/list Package list contains the implementation of the "source list" command.	Package list contains the implementation of the "source list" command.
internal/commands/source/signin Package signin contains the implementation of the "source sign-in" command.	Package signin contains the implementation of the "source sign-in" command.
internal/commands/source/signout Package signout contains the implementation of the "source sign-out" command.	Package signout contains the implementation of the "source sign-out" command.
internal/commands/version Package version contains the implementation of the "version" command.	Package version contains the implementation of the "version" command.
internal/completion Package completion contains utilities for implementing shell auto-completion.	Package completion contains utilities for implementing shell auto-completion.
internal/flags Package flags configures and reads global ("persistent") flags and flags that are used by multiple commands.	Package flags configures and reads global ("persistent") flags and flags that are used by multiple commands.
internal/render Package render contains utilities for formatting values for display.	Package render contains utilities for formatting values for display.
internal/shell Package shell provides an abstraction used to execute shell commands within the context of the CLI's parent shell.	Package shell provides an abstraction used to execute shell commands within the context of the CLI's parent shell.
internal/style
cmd
grit Package main is the CLI executable.	Package main is the CLI executable.
gritd Package main is the daemon executable.	Package main is the daemon executable.
daemon Package daemon is the entry-point for the Grit daemon executable.	Package daemon is the entry-point for the Grit daemon executable.
internal/apiserver Package apiserver contains the implementations of the gRPC services provided by the daemon.	Package apiserver contains the implementations of the gRPC services provided by the daemon.
internal/builtins/githubsource Package githubsource is a source driver that integrates Grit with GitHub.	Package githubsource is a source driver that integrates Grit with GitHub.
internal/builtins/gitvcs Package gitvcs is a VCS driver that integrates Grit with Git.	Package gitvcs is a VCS driver that integrates Grit with Git.
internal/config Package config parses, validates and normalizes configuration files.	Package config parses, validates and normalizes configuration files.
internal/driver/configtest Package configtest provides utililities to help driver developers test their integration with Grit's configuration system.	Package configtest provides utililities to help driver developers test their integration with Grit's configuration system.
internal/driver/sourcedriver Package sourcedriver defines the API used to implement source drivers.	Package sourcedriver defines the API used to implement source drivers.
internal/driver/vcsdriver Package vcsdriver defines the API used to implement VCS (version control system) drivers.	Package vcsdriver defines the API used to implement VCS (version control system) drivers.
internal/logs Package logs provides a simple logging interface.	Package logs provides a simple logging interface.
internal/signalx Package signalx provides utilities for working with signals.	Package signalx provides utilities for working with signals.
internal/source Package source provides an abstraction of a "repository source" which is any service that hosts source repositories that can be searched and cloned by Grit.	Package source provides an abstraction of a "repository source" which is any service that hosts source repositories that can be searched and cloned by Grit.
internal/stubs