Install¶

git-city is a small Python CLI managed with uv. It is in early/pre-release, so there is no PyPI package yet — you install it from source. This page covers the prerequisites, installing the git-city tool, how it becomes a git subcommand, the developer workflow, and how to verify your install.

Prerequisites¶

Requirement	Version	Why
Python	`>= 3.12`	Runtime for git-city
Git	any recent version	git-city drives Git under the hood
uv	recent	Builds, installs, and runs the tool

git-city's runtime dependencies (the cyclopts CLI framework and InquirerPy for interactive pickers) are installed for you — you do not need to manage them by hand.

Note

git-city has no forge integration yet. It works fully against a plain Git remote, or with no remote at all. See forge-agnostic and the roadmap for what is and is not built.

Install from source¶

Clone the repository, then install it as a uv tool from the project directory:

git clone https://github.com/fermigier/git-city.git
cd git-city
uv tool install .

uv tool install . builds git-city and installs the git-city executable onto your PATH in an isolated environment, so it is available from any repository on your machine.

Tip

If git-city is not found after install, make sure uv's tool directory is on your PATH. Run uv tool update-shell and restart your shell.

`git city` is a Git subcommand¶

The executable is named git-city. Git automatically treats any executable named git-<something> on your PATH as a subcommand, so once installed you can call it either way:

git-city tree   # direct invocation
git city tree   # as a Git subcommand

The two are equivalent. This documentation uses the git city <cmd> form throughout because it reads naturally alongside the rest of your Git workflow.

Developer usage (`uv run`)¶

If you are working on git-city itself, you do not need to install it globally. Run it straight from a checkout with uv, which resolves the project's environment on the fly:

uv run git-city tree
uv run python -m git_city tree

Both forms run the in-tree code, so your edits take effect immediately without reinstalling.

Verify it works¶

Check that the tool is installed and callable:

git city --help

Then, from inside any Git repository, run the read-only dashboard:

git city info

(Bare git city, with no command, prints the grouped command menu — handy for discovering what is available.)

In a repository with a feature branch, you will see something like this:

git-city · my-project
  trunk:  main
  remote: origin

on  ● add-login   (feature, parent: main)
    working tree: clean
    vs main:  ↑2 ↓0
    vs origin/add-login:  ↑0 ↓0

stack:
main  (trunk)
└─ ● add-login  ↑2 ↓0

The dashboard is completely read-only — it never touches your branches — so it is a safe first command to confirm everything is wired up.

Note

On a fresh repository, run git city init first to record your trunk branch. It auto-detects main/master, or lets you pick on a TTY.

Next steps¶

You are installed and ready to go.

→ Quick start