git

Inspect and modify repositories using a subset of the Git command line. Mirage routes repository files through the workspace dispatcher, so the same commands can operate on RAM, disk or another backend with the required filesystem operations. The Python implementation uses Dulwich; the TypeScript implementation uses isomorphic-git. Mirage supplies the command grammar, output and VFS integration on both hosts. The compatibility target is native Git’s supported behavior, with the differences below. These libraries are implementation dependencies; their own command interfaces do not define Mirage’s supported commands.

Setup

git has no account config. It needs an existing repository to inspect, or a writable mount on which to initialize or clone one.

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.git import GIT
from mirage.vfs.ram import RAMVFS

ws = Workspace({"/repo": RAMVFS()}, mode=MountMode.WRITE)
ws.register_cli("git", GIT)
await ws.shell("git -C /repo init -b main")

For YAML registration, see the CLI overview.

Supported commands

Run git <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Command	Description
`git reflog`	Show reference history
`git for-each-ref`	List references with a format
`git cat-file`	Provide contents or details of repository objects
`git hash-object`	Compute object ID and optionally create an object from a file
`git grep`	Search tracked files in the working tree, index or named trees
`git ls-tree`	List the contents of a tree object
`git ls-files`	Show files in the index
`git fetch`	Download objects and refs from another repository
`git clone`	Clone a repository into a new directory
`git help`	Show command help
`git init`	Create an empty Git repository or reinitialize an existing one
`git fsck`	Verify object hashes and connectivity
`git stash list`	List stashed changes
`git stash show`	Show stashed changes
`git version`	Show the Mirage Git implementation version. Aliases: `--version`, `-v`.
`git remote`	List remotes and inspect their URLs
`git config`	Read repository configuration
`git merge-base`	Find best common ancestors of commits
`git show-ref`	List references
`git symbolic-ref`	Read, change or delete a symbolic ref
`git shortlog`	Summarize commit history
`git rev-parse`	Resolve revisions
`git rev-list`	List reachable commits
`git diff-tree`	Compare a commit with its parent
`git status`	Show the working tree status
`git log`	Show commit logs
`git show`	Show a commit and its diff
`git diff`	Show changes between commits
`git branch`	List, create or delete branches
`git add`	Stage working tree content
`git reset`	Unstage, putting the index back to HEAD
`git commit`	Record the index as a new commit
`git checkout`	Switch branches
`git switch`	Switch branches
`git restore`	Restore working tree files
`git rm`	Remove files from the working tree and the index
`git mv`	Move or rename a file, a directory, or a symlink
`git tag`	Create, list or delete a tag

Create and inspect a repository

git -C /repo init -b main
echo hello > /repo/hello.txt
git -C /repo add hello.txt
git -C /repo commit -m 'Initial commit'
git -C /repo status --short
git -C /repo log --oneline -5
git -C /repo show HEAD
git -C /repo diff
git -C /repo diff --cached
git -C /repo grep -n hello
git -C /repo ls-files --stage
git -C /repo fsck

-C selects a workspace directory and defaults to the session’s working directory. Repository discovery walks upward, so commands also work from subdirectories. Loose objects, packs, refs, the index and working files all use the same VFS operations as the shell. init supports -b, --bare and reinitialization. The default branch is master unless -b chooses another. commit requires -m and records mirage <mirage@localhost> unless --author 'Name <email>' overrides it. fsck checks the object database without modifying it.

Stage and change files

Continue from the initial commit above. Record a second version before using HEAD~1 to restore the original:

echo updated > /repo/hello.txt
git -C /repo commit -am 'Update greeting'
git -C /repo add -A
git -C /repo reset -- hello.txt
git -C /repo restore -- hello.txt
git -C /repo restore --staged -- hello.txt
git -C /repo restore --source HEAD~1 -- hello.txt
git -C /repo commit -am 'Restore original greeting'
git -C /repo mv hello.txt greeting.txt
git -C /repo commit -m 'Rename greeting'
git -C /repo rm greeting.txt
git -C /repo commit -am 'Remove greeting'

Command	Behavior
`add`	`-A` stages all changes, `-u` tracked changes, `-f` allows ignored paths
`reset`	Mixed reset from HEAD, optionally limited by paths; no revision operand or hard reset
`restore`	Worktree by default, `--staged` for the index, `-SW` for both; `--source` accepts a tree-ish
`rm`	Refuses uncommitted changes unless `-f`; `--cached` keeps working files; `-r` allows directories
`mv`	Files or directories; supports force, dry-run, verbose and skip-failure modes; cannot cross mounts
`commit`	Commits the whole index; `-a` restages tracked files, `--allow-empty` permits an empty change

restore can discard changes in the selected destination. Use -- before a path beginning with -. Permission and read-only refusals go through the workspace dispatcher and are reported in Git’s command-specific wording.

Branches, tags and history

git -C /repo branch topic
git -C /repo switch topic
git -C /repo switch -c experiment
git -C /repo checkout --detach HEAD~1
git -C /repo branch --contains HEAD
git -C /repo tag v1.0
git -C /repo tag -a v1.1 -m 'Release'
git -C /repo for-each-ref --format='%(refname:short)' refs/heads
git -C /repo reflog
git -C /repo stash list

Annotated tags need -m; lightweight tags can point to any object. Revision expressions include parent/ancestor operators (^, ~), typed peels such as HEAD^{tree}, and paths such as HEAD:hello.txt. Operators apply left to right. Invalid suffixes are refused as part of the whole revision. log, show, rev-list, diff-tree, shortlog, cat-file, hash-object and ls-tree provide inspection without a host Git process. Run each command’s --help for supported formatting, filtering, path and diff options.

Clone, fetch and repository configuration

git clone /repo /work/copy
git clone https://github.com/acme/tools.git /work/tools
git -C /work/tools fetch origin
git -C /work/tools remote -v
git -C /work/tools config --get remote.origin.url
git --git-dir=/repo/.git --work-tree=/repo status --short

Clone and fetch can read another workspace repository or a smart-HTTP remote. Destinations must be writable mounts. There is no push or pull command. A path git refuses to check out is refused by checkout, switch, restore and reset as git refuses it; git clone then exits 128 and keeps the repository with an empty work tree. Reading the entries of a tree that holds an entry with an empty name exits 128 with git’s empty filename in tree entry. For authenticated GitHub clones, gh repo clone supplies its configured token, and only to its configured GitHub origin. --git-dir and --work-tree override GIT_DIR and GIT_WORK_TREE and resolve against -C. Repository core.worktree and core.bare affect discovery; linked worktrees use their recorded layout. Working-tree commands refuse bare repositories. No repository operation opens a host path behind the VFS.

Limits and intentional differences

Only the listed command subset is implemented. Merge, rebase, push, pull, reset --hard and switch - are absent; stash supports inspection only.
Commits accept no path operands and do not create merge commits. An unmerged index blocks commits and branch moves. checkout is stricter than Git about staged changes; switch can carry compatible staged changes but refuses file/directory collisions that would discard them.
Host templates, hooks, editors and Git’s initial-branch advisory are absent. Per-worktree config.worktree is not read. With conflicting core.bare and core.worktree, Mirage keeps the repository bare without Git’s warning.
Working-tree replacements preserve executable modes and symlink semantics. They do not follow a symlink out of a directory being replaced. Nested mounts block removals or replacements that would consume their contents; destinations are checked before writes begin. Renames preserve namespace metadata and cannot cross mount boundaries at either end.
Gitlinks create or retain directory placeholders. Mirage does not check out submodule content or compare a submodule’s HEAD; files inside a submodule directory can still appear as untracked. Removing a nonempty gitlink directory warns and leaves it in place.
Diff hunk bodies and diffstat counts can differ from native Git because the line-diff algorithm differs from xdiff. Headers, ordering and supported formatting match Git. Pretty formats email, mboxrd and reference are refused.
History searches use ASCII case folding. --since and --until accept ISO-8601 or epoch seconds; relative date phrases are refused.
tag -l/-d conflict wording uses a fixed option order. Tag deletion uses a ref transaction: duplicate updates are refused atomically, while missing names are reported and skipped.

These boundaries are exercised by the shared Git integration corpus on RAM and disk mounts. The VFS determines which filesystem operations are available; registering git does not make a read-only mount writable.

Upstream and dependency licenses

Project	Role in Mirage	License
Git	Command behavior and repository-format reference; Mirage’s CLI does not launch the native Git executable	GPL-2.0, with the qualifications in Git’s COPYING file
Dulwich	Python Git implementation dependency	Apache-2.0 OR GPL-2.0-or-later
isomorphic-git	TypeScript Git implementation dependency	MIT
Mirage	Command layer and VFS adapters	Apache-2.0

Dulwich offers an Apache-2.0 option; using it does not require choosing its GPL alternative. Matching Git behavior does not relicense Git, Dulwich or isomorphic-git. Copied or ported source and redistributed dependencies still carry their applicable terms and notices; see compatibility and licenses.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Setup

Supported commands

Create and inspect a repository

Stage and change files

Branches, tags and history

Clone, fetch and repository configuration

Limits and intentional differences

Upstream and dependency licenses

​Setup

​Supported commands

​Create and inspect a repository

​Stage and change files

​Branches, tags and history

​Clone, fetch and repository configuration

​Limits and intentional differences

​Upstream and dependency licenses

Setup

Supported commands

Create and inspect a repository

Stage and change files

Branches, tags and history

Clone, fetch and repository configuration

Limits and intentional differences

Upstream and dependency licenses