Installation

pip install git-project
pip install git-project-core-plugins

git-project needs Python 3.10 or later.

Overview

git-project is a git extension for managing development work in a git repository. By itself it does almost nothing. It provides -h, --version and --menu, and plugins provide the commands.

git-project-core-plugins provides the basic commands, among them clone, init, worktree, branch, run and config. Install it alongside git-project.

git-project aims to make switching between tasks in a repository fast, without losing the state of the tasks you set aside. For example, the core plugins can give each worktree its own build directory, so moving to another worktree does not rebuild everything.

Projects

git-project runs under the name of a link to it, and that name selects the active project. If git-fizzbin is a symlink to git-project, then git fizzbin <command> runs git-project with fizzbin as the active project. Run as git-project itself, the active project is project. These docs write git <project> for whichever name you use.

Create the link yourself, in a directory on your PATH:

ln -s "$(command -v git-project)" ~/.local/bin/git-fizzbin

Each project keeps its settings apart from the others, so one repository can hold several projects, each run through its own link.

Configuration

git-project stores its settings in the repository’s git config. A project’s settings live in a section named after the project. git-project changes . and _ in the name to -, so the project fizz_bin uses the section fizz-bin.

Whenever they are missing, git-project sets two values in the project section: branch, the repository’s main branch, and remote, which is origin.

Plugins keep their own settings in subsections of the project section. For example, a project with one worktree might hold:

[fizzbin]
    branch = main
    remote = origin
    srcdir = /src
[fizzbin "worktree.main"]
    builddir = {srcdir}/build

A key can hold more than one value. On every run, git-project also checks the config file and stops if one section holds the same key = value line twice.

Scopes

A scope is a subsection that a plugin makes active for the current run. While a scope is active, a value set in the scope overrides the same key in the project section. For example, when you run inside a worktree, the core plugins’ worktree plugin makes that worktree’s subsection a scope. A value set for one worktree then applies only there.

The name of an active scope is also a substitution variable, and its value is the scope’s identifier. In the example above, {worktree} is main inside the main worktree.

Substitution

Some values are substituted before they are used, for example the commands that the run plugin runs. Substitution replaces {name} with the value of name. A name can be:

• a key in the project section

• a key in the object being substituted, or in an active scope

• the name of an active scope, as above

• one of these built-in names

project

The active project’s section name

branch

The checked-out branch, or during a rebase the branch being rebased

gitdir

The repository’s git directory

git_common_dir

The git directory that all worktrees share

git_workdir

The root of the current worktree

Substitution repeats until the value stops changing, so a value can name another value that itself contains {name}. A value may not name itself. To write a literal brace, write {{} for { and {}} for }. A name is ASCII letters, digits and underscores, and does not start with a digit. Other text in single braces, such as {x.upper()} or {}, stays as written, but a doubled {{ or }} becomes one brace. A name that is not defined is an error.

Substitution inserts each value as written, and the run plugin runs its commands through a shell. Treat the git config as code, and do not include config from a source you do not trust.

Getting help

git <project> -h lists the commands that the installed plugins provide. Use -h there, because git turns git <project> --help into a request for a man page. After a command name --help works as usual, and with the core plugins installed git <project> help <command> shows a command’s full manual.

--menu lists a command’s subcommands, arguments and options in a form meant for tools. --menu=json prints them as one JSON object and adds each subcommand’s aliases and each argument’s nargs and choices. An option’s name is its long flag when it has one. --menu=json-tree prints the same object with each subcommand’s own object nested under its menu key, so one call returns every level. The version field changes only when a key is removed or changes meaning, so a reader should ignore keys it does not know.

nargs is null when the argument takes argparse’s default, one value or none for a switch. Otherwise it is a count such as "2", or "?", "*", "+" or "...", which takes every remaining word as written. Three keys help a tool offer values. complete names the kind of value: branch, committish, directory, file, remote or worktree, a git-project worktree name. A null or unknown complete means free text. candidates lists values to suggest, which unlike choices the command does not enforce. repeatable is true when each use of an option adds to its value rather than replacing it.

License

git-project is distributed under the terms of the GNU Affero General Public License v3.0 or later.

Authors

git-project is written and maintained by David Greene.