git-dummy

Git repositories on demand: generate the exact history, remote, and working-tree state you need for tests, demos, tutorials, and practice, without touching real data.

• Build any repo shape in one command: linear, divergent, commits, branches, merges, tags, a stopped merge conflict, untracked files, modified files, staged files, stashes, a remote that is ahead or behind, a detached HEAD, worktrees, and submodules.
• Start from a named scenario for the situations people actually get into, like a conflicted merge, a diverged remote, rebase-ready, or a dirty working tree.
• Make it look real, and reproducible: real-looking files, commit messages, and authors, persistent object ID's by specifying a starting seed, and large histories fast through git fast-import.
• Use it anywhere: a one-liner in the terminal, a Python API that returns the paths, ids, and states it made, a recipe file, or a plain shell script of git commands for machines without Python.
• Agentic: your agents can use it as a part of their testing flows if they depend on Git repo structure / state.

The graph above is the history scenario, drawn by git-sim.

Requirements

• Python 3.8 or later
• Git 2.28 or later on your PATH: git-dummy runs your own git, and needs nothing else

Get started

1. Install git-dummy

$ pip install git-dummy

Or pipx install git-dummy, or uv tool install git-dummy.

2. Build a repo: in the folder you want it in, ask for the shape

$ git-dummy --commits=10 --branches=4 --merge=1

This creates a repo called dummy by default (override with --name=<name>), in the current folder, with 4 branches of up to 10 commits each, and branch1 merged back into main.

Run git-dummy -h to list all options.

3. Start from a scenario: the situation you want to practice, test, or demo

$ git-dummy --scenario merge-conflict       # a merge stopped on a conflict, markers in the file
$ git-dummy --scenario diverged-remote      # local and remote both moved on: push is rejected, pull merges
$ git-dummy --list-scenarios                # list all available scenarios

4. Make it look real: like a small web service with real-looking files, messages, and authors, consistent across generations via the same seed

$ git-dummy --style realistic --seed 42 --commits 8 --branches 2 --remote --behind 2 --ahead 1

5. Build one in a test: the Python API returns everything git-dummy made

from git_dummy import build

repo = build(scenario="rebase-ready", git_dir=tmp_path)
repo["branches"]["main"]   # the tip of main

6. See it: draw the repo with git-sim, and visually simulate Git commands on it

$ git-dummy --scenario orders
$ cd orders
$ git-sim log --all

Scenarios

git-dummy --scenario <name> starts from one of these, and specifying additional options (like --commits or --branches overrides the scenario's defaults. List all scenarios with git-dummy --list-scenarios

Python API

from git_dummy import build, Spec

r = build(commits=6, branches=2, style="realistic", seed=7, remote=True, behind=2, git_dir="/tmp")
r["path"]                  # where it is
r["branches"]["main"]      # tip ids
r["remote"]["path"]        # the bare remote beside it
r["worktree"]["staged"]    # what is staged, modified, untracked, in conflict
r["commits"]               # every commit: sha, parents, author, message

build(scenario="merge-conflict", git_dir="/tmp", name="cx")
build(Spec.from_recipe("repo.yaml"))

git_dummy.script(spec) returns the shell script, and git_dummy.clean(path) removes a repo git-dummy made. Use it to generate repos for functional tests of Git tools, with the exact shape a test needs.

Recipes, scripts, and cleanup

A recipe file holds the same options as the command line, in JSON or YAML. --print-script writes the plain git commands that would build the repo instead of actually doing it, for a machine without Python or a tutorial's appendix:

$ cat repo.json
{"scenario": "rebase-ready", "name": "practice", "commits": 8}
$ git-dummy --from repo.json
$ git-dummy --from repo.json --print-script > build-practice.sh

--json prints a description of what was built, and --clean removes a repo git-dummy made, and nothing else.

What gets created where

By default git-dummy creates a project folder called dummy and initializes the dummy Git repo with .git/ folder in there. Override that with by specifying --git-dir and/or --name, which will create the repo at <git-dir>/<name> (or put the .git/ folder in the current directory with --no-subdir). Everything else git-dummy makes sits beside it and is listed in the repo's .git/git-dummy.json, which is what --clean reads:

• <name>.git: the bare remote (--remote)
• <name>-<branch>: a linked worktree (--worktree)
• <name>.lib: the library a submodule points at (--submodule)

Every repo has at least one branch, main. Other branches are named branch1, branch2, and so on (or given with --branch-names, or realistic names with --style realistic). Each branch diverges from main at --diverge-at if given, or else at a randomly chosen commit, and is at most --commits long. --merge=<x>,<y> picks which branches are merged back into main.

Options

$ git-dummy [options]

The ones you'll reach for most:

--name <name>, --git-dir <path>: what to call the repo, and where to put it
--commits <number>, --branches <number>, --merge <x>,<y>: the shape of the history
--scenario <name>: start from a named scenario
--style realistic, --seed <number>: real-looking content, the same every time
--remote, --ahead <number>, --behind <number>: a remote, and how far apart they are
--modified, --staged, --untracked, --stashes, --conflict: something in the working tree

Every option can also be set with an environment variable named git_dummy_ plus the option, such as git_dummy_git_dir=~/Desktop or git_dummy_style=realistic. Specifying an option on the command line overrides the environment variable.

Installation

$ pip install git-dummy

Or pipx install git-dummy, or uv tool install git-dummy. YAML recipe files need PyYAML, which pip install "git-dummy[yaml]" adds. JSON recipes always work.

Learn more

Learn more on the git-dummy project page. git-dummy is what git-sim uses for its demos, its tests, and the graphs in its README, and git-dummy powers all Git simulations on the Initial Commit website including:

• The animated Git cheat sheet: pick the commands you use and print your own sheet, each with an animation of what it does to your repo
• The visual Git command reference: every command git-sim simulates, each drawn on a sample repo
• The Git command articles: one page per command, with interactive before-and-after simulations

Support git-dummy

git-dummy is free and open-source software. Your support helps me work on it, and other Git projects, full time:

• ⭐ Star the repo
• Sponsor Initial Commit on GitHub
• Support Initial Commit via Patreon

Authors

Jacob Stopak - on behalf of Initial Commit