Git Tools

Personal Git tools for common repository workflows.

Tools

• git-workspace organizes a repository around linked Git worktrees.
• git-new creates a bare repository with an initial empty commit.

git-workspace

git-workspace organizes a repository around linked Git worktrees. The workspace root contains a bare repository at .git, while each checked-out branch lives in a sibling subdirectory.

project/
|-- .git/          bare common repository
|-- main/          linked worktree
|-- feature-one/   linked worktree
`-- review/        linked worktree

Because the executable is named git-workspace, Git exposes it as git workspace.

Requirements

• Python 3.11 or newer
• Git
• uv, which the Makefile uses for Python tooling

The installed application has no Python package dependencies. Ruff, ty, and pytest are development-only dependencies.

Install

Install all included tools and the Bash completion from the project checkout:

sudo make install

Reinstall after local changes:

sudo make install

Usage

Clone a repository into a workspace:

git workspace https://github.com/example/project.git
git workspace https://github.com/example/project.git local-name

Create a new repository and its initial worktree:

git workspace --new project
git workspace --new project -b topic

Add a worktree from any existing worktree in the workspace:

git workspace -w feature/topic
git workspace -b feature/topic
git workspace -B existing-branch
git workspace -w review -b feature/topic

Branch behavior:

Options	Worktree path	Branch behavior
-w NAME	NAME	Reuse NAME, or create it from the invoking HEAD
-b BRANCH	BRANCH	Create BRANCH; fail if it exists
-B BRANCH	BRANCH	Reuse BRANCH unchanged, or create it
-w PATH -b BRANCH	PATH	Create BRANCH at a separate path
-w PATH -B BRANCH	PATH	Reuse or create BRANCH at a separate path

Existing branches are never reset or moved. A newly created worktree branch starts at the HEAD of the worktree where the command was invoked.

Worktree administrative links are relative, so the complete workspace can be moved as one directory. Git 2.48 and newer handles this natively. Older versions use a portable Python fallback that rewrites both sides of the worktree link.

Development

Create the development environment:

make sync

Run all checks:

make check

Run individual checks or format the code:

make format
make lint
make typecheck
make test

Build release artifacts with:

make package

Use make dist to build only the source distribution.

git-new

Create a bare repository with an initial empty commit:

git-new project.git