git-project - The extensible stupid project manager

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 value is evaluated as Python. git-project substitutes a value by evaluating it as a Python f-string. So {1+1} becomes 2, and any Python expression in braces runs when the value is substituted. Treat the git config as code, and do not include config from a source you do not trust. A value that contains a ' cannot be substituted.

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.

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.

0.0.40 - 2026-10-05

Added

capture_command takes a list of arguments as well as a string.
The package ships a py.typed marker, so mypy checks code that uses git-project against its annotations.

Changed

GitProjectException is now GitProjectError. The old name still works as an alias, and a later release removes it.
The git_project._contributing module is gone. The guide to working on git-project is in the docs only, and its Tests section is now the git_project.test_support package documentation.

Fixed

substitute_value, substitute_command and run shared one default formats dict across calls, and substitute_value added its names to it. So within one process, an object could resolve a name it does not define to another object’s value. Each call now works on its own copy, and a formats dict passed in is no longer changed.
Removing one value of a config key failed when the value held a space. It was split into several arguments to git config --unset. The pattern now reaches git as given, so a pattern escaped twice to get through that split must be escaped once.
Git.get_git_common_dir returns an absolute path in a worktree that plain git worktree add made. It returned the relative path that git writes, so {git_common_dir} substituted ../.. there.

Full Changelog

Metadata

Release files for git-project 0.0.40

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for git-project 0.0.40
File	Size	Uploaded
git_project-0.0.40.tar.gz	66.0 kB	Oct 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for git-project 0.0.40
File	Interpreter	ABI	Platform	Reset
git_project-0.0.40-py3-none-any.whl 62.7 kB Oct 5, 2026	Python 3	none	any	Details

Total release size: 128.8 kB

Release files / git_project-0.0.40.tar.gz

Download URL	git_project-0.0.40.tar.gz
Size	66.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`10c0533aa2b3b3bf23a49427b91cbc4b78bbb2004660dbbfcbce406d1e394c53`
BLAKE2b-256 checksum How to use checksums	`3a6e478b9662bbd6be4f9f3fbd675c38b9b1c939f5475f2c1e52c55cf59148be`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / git_project-0.0.40-py3-none-any.whl

Download URL	git_project-0.0.40-py3-none-any.whl
Size	62.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`71d60ac84a850a156c8c9c5e39def8088b7a53a33e913c3959acf2e4219c2bb7`
BLAKE2b-256 checksum How to use checksums	`34398bef6f3e59d65355a7ef1b8b5a4b96d0194cb874581ffcfa003d29d403cc`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`