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

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.42 - 2026-10-06

Added

A command can set write_project_defaults=False on its parser, so that git-project does not write the project’s default branch and remote to the config. A dry run can then leave the config as it was.
Project.get takes set_defaults, True by default. With False, it does not write the defaults.

Changed

git-project writes the project defaults after the command line is parsed, not when it builds the project. So -h, --version, --menu and a command-line error no longer write them. The plugin hooks add_class_hooks, add_arguments and modify_arguments can see a project without its default branch and remote.

Fixed

branch prune, worktree rm and Project.prune_branch stopped and kept the local branch when a remote could not be reached, such as one whose URL names a host alias from ~/.ssh/config, which libgit2 does not read, or when a remote refused the delete. They now warn about that remote on stderr and delete the local branch.

Full Changelog

Metadata

Release files for git-project 0.0.42

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.42
File	Size	Uploaded
git_project-0.0.42.tar.gz	69.0 kB	Oct 7, 2026	Details

Built distribution (wheel)

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

Total release size: 132.4 kB

Release files / git_project-0.0.42.tar.gz

Download URL	git_project-0.0.42.tar.gz
Size	69.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`4010d5be8fdd2f00f74769b00d8d869651a23f8e895bf4546330ae9709e989f5`
BLAKE2b-256 checksum How to use checksums	`4c684c787403cb32a60aa54d06aafe643c0bf2c962b7bcc519e9435b71cefe70`
Upload date	Oct 7, 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.42-py3-none-any.whl

Download URL	git_project-0.0.42-py3-none-any.whl
Size	63.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`902af5db73bc6823b5d81d7b775f4165676255afdac745d086643779c3582ea1`
BLAKE2b-256 checksum How to use checksums	`482ae77de46356a5df2d39ccba2ce96e6467fed562b811032262761d2bea5b4e`
Upload date	Oct 7, 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}`