CLI Reference

Pitmaster includes a CLI that mirrors a subset of git commands. It operates on the repository in the current working directory.

./vendor/bin/pitmaster <command> [args...]

From a Composer install the script is ./vendor/bin/pitmaster; since 0.2.11 it finds the project's autoloader there. In a checkout of the Pitmaster repository itself, run ./bin/pitmaster after composer install. The examples below use pitmaster for either path. Running it without arguments prints the command list.

Revisions are resolved like Repository::resolve(): HEAD, branch and tag names, full ref names, full hashes, and ~N / ^N expressions. Abbreviated hashes are not accepted. Clone, fetch, and push are available only through the PHP API.

Commands

log

Show commit history, newest first.

# Default: last 10 commits
pitmaster log

# Limit the number of commits
pitmaster log 25
pitmaster log -n 3
pitmaster log -n3
pitmaster log --max-count 3
pitmaster log --max-count=3
pitmaster log -3

# Commits that touch one file
pitmaster log src/Repository.php
pitmaster log -- src/Repository.php

# Commits reachable from all refs, and one line per commit
pitmaster log --all
pitmaster log --oneline

The git limit spellings (-n N, -nN, --max-count N, --max-count=N, -N) were added in 0.2.11. A bare number is Pitmaster's own shorthand for the limit. The first other argument is a path filter; everything after -- is treated as the path. Any other argument starting with - prints fatal: unrecognized argument: <arg> and exits with 128.

Output includes commit <hash> (yellow), a Merge: line for merge commits, Author: with the raw identity (name, email, timestamp and timezone), and the commit message indented. --oneline prints abc1234 Subject. The path filter matches one exact file path and examines only the newest five times the limit commits (#7).

show

Show commit details and diff against the first parent.

# Show HEAD
pitmaster show

# Show a specific commit
pitmaster show HEAD~3
pitmaster show v1.0.0
pitmaster show 3f2c1e0b9d6a4f8e7c5b2a1d0e9f8c7b6a5d4e3f

Displays the commit metadata (with a Date: line) followed by a unified diff. For an annotated tag, the tag header and message come first. Colors are used only when stdout is a terminal. Merge commits are shown without a diff.

cat-file

Print the raw content of a git object.

pitmaster cat-file a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Takes a full hash. Prints the object's stored content: blobs, commits, and tags as text, trees in their binary form. Unlike git cat-file -p, trees are not pretty-printed.

status

Show working tree status.

pitmaster status
pitmaster status --porcelain=v2

Output:

On branch main

Changes to be committed:
	new file:   src/Feature.php

Changes not staged for commit:
	modified:   src/Existing.php

Untracked files:
	notes.txt

Staged files are shown in green, unstaged, unmerged, and untracked in red. An Unmerged paths: section appears during a conflicted merge. A detached HEAD prints HEAD detached, and a clean tree prints nothing to commit, working tree clean. --porcelain=v2 prints the output of Repository::statusPorcelainV2().

diff

Show changes between the index and the working tree (unstaged changes).

# Unstaged changes
pitmaster diff

# Staged changes (index vs HEAD)
pitmaster diff --cached
pitmaster diff --staged

# Choose the algorithm
pitmaster diff --patience
pitmaster diff --histogram
pitmaster diff --minimal

Output is a colorized unified diff, also when stdout is not a terminal. It matches git diff for modified text files; new, deleted, binary, renamed, and mode-changed files are formatted differently (see Diff). diff --cached prints nothing before the first commit (#5).

add

Stage files for the next commit.

pitmaster add src/Feature.php
pitmaster add src/Feature.php tests/FeatureTest.php README.md

Each file is read from the working tree, written as a blob object, and the index is updated. Arguments are file paths; directories and . are not expanded.

commit

Create a commit from the staged files.

pitmaster commit -m "Add new feature"

Output:

[main abc1234] Add new feature

-m is required, except when completing a stopped merge, cherry-pick, revert, or rebase, where the prepared message is used. The author and committer are resolved from environment variables, constants, and .git/config, as described in Getting Started.

branch

List branches or create a new one.

# List all branches (current marked with *)
pitmaster branch

# Create a new branch from HEAD
pitmaster branch feature/new-thing

# Delete a branch
pitmaster branch -d feature/old
pitmaster branch -D feature/old

Output for listing:

  bugfix/typo
  feature/login
* main

Creating prints Created branch <name>, deleting prints Deleted branch <name>. -d and -D behave the same: neither checks whether the branch is merged, and both refuse to delete the checked-out branch.

tag

List tags or create a new one.

# List all tags
pitmaster tag

# Create a lightweight tag at HEAD
pitmaster tag v1.0.0

# Create an annotated tag at HEAD
pitmaster tag v2.0.0 -m "Release version 2.0.0"

Creating prints Created tag <name>.

checkout

Switch branches or detach HEAD.

# Switch to a branch
pitmaster checkout feature/login

# Detach HEAD at a tag or commit
pitmaster checkout v1.0.0
pitmaster checkout HEAD~2

Updates HEAD, the index, and the working tree to match the target, and prints Switched to '<target>'. It refuses when local changes or untracked files are in paths that differ between the two trees. Uncommitted changes in other tracked files are overwritten with the target's content, where git would keep them (#2); commit or stash them first.

merge

Merge one or more branches into the current HEAD, or continue/abort an in-progress merge conflict.

# Start a merge
pitmaster merge feature/login

# Merge with a strategy
pitmaster merge -s ours feature/login

# Octopus merge of several branches
pitmaster merge feature/a feature/b

# Continue after resolving conflicts
pitmaster add a.txt
pitmaster merge --continue

# Abort and restore the pre-merge state
pitmaster merge --abort

Output on success:

Merge successful.

Output on conflict (on stderr, exit code 1):

CONFLICT in: src/File.php, src/Other.php

-s accepts ours, ort, and recursive; ort and recursive both use the default merge. With -s, the CLI prints Merge successful. and exits with 0 even when the merge stopped on conflicts (#21), so check status afterwards. merge --continue without a merge in progress exits with 128. Merging a branch that is already merged creates another merge commit (#6), and uncommitted changes in tracked files are overwritten as with checkout.

cherry-pick

Apply a commit on top of the current HEAD, or continue/abort an in-progress conflict.

# Start a cherry-pick
pitmaster cherry-pick feature~1

# Continue after resolving conflicts
pitmaster add a.txt
pitmaster cherry-pick --continue

# Abort and restore HEAD
pitmaster cherry-pick --abort

Prints nothing on success. --continue and --abort without a cherry-pick in progress exit with 128.

revert

Create a revert commit, or continue/abort an in-progress conflict.

# Start a revert
pitmaster revert HEAD~1

# Continue after resolving conflicts
pitmaster add a.txt
pitmaster revert --continue

# Abort and restore HEAD
pitmaster revert --abort

Prints nothing on success. --continue and --abort without a revert in progress exit with 128.

rebase

Rebase the current branch onto another ref.

# Start a rebase
pitmaster rebase main

# Continue after resolving conflicts
pitmaster rebase --continue

# Skip the current commit
pitmaster rebase --skip

# Abort and restore the original branch tip
pitmaster rebase --abort

Prints nothing on success. --continue, --skip, and --abort without a rebase in progress print fatal: no rebase in progress and exit with 128.

bisect

Find the commit that introduced a change by binary search.

# Start with a bad and a good revision; checks out and prints the first candidate
pitmaster bisect start HEAD v1.0.0

# Mark the checked-out candidate (or a given revision)
pitmaster bisect good
pitmaster bisect bad
pitmaster bisect bad HEAD~3

# End the session and return to the starting branch
pitmaster bisect reset

start, good, and bad print the full hash of the next candidate, which is checked out. When only one suspect is left, the same hash is printed again: that commit is the first bad commit. Unlike git, no "is the first bad commit" summary is printed.

stash

Save and restore working directory changes.

# Save current changes (push)
pitmaster stash
pitmaster stash push
pitmaster stash push "Work in progress on login"
pitmaster stash save "Work in progress on login"

# Apply and remove the top stash entry
pitmaster stash pop

# Apply without removing
pitmaster stash apply

# List stash entries
pitmaster stash list

# Drop the top stash entry
pitmaster stash drop

The message is the argument after push or save; -m is not supported and would be stored as the message. pop, apply, and drop always use stash@{0}. They print Saved working directory to stash abc1234, Applied and dropped stash, Applied stash, and Dropped stash.

Stash list output:

stash@{0}: On main: Work in progress on login
stash@{1}: WIP on main: abc1234 Add new feature

With more than one entry, drop and pop currently leave the entry in the list (#10), and apply overwrites uncommitted changes in files the stash does not touch (#11).

blame

Show line-by-line authorship of a file at HEAD.

pitmaster blame src/Repository.php

Output:

a1b2c3d4 (Jane Smith <jane@example.com> ) <?php
a1b2c3d4 (Jane Smith <jane@example.com> )
f5e6d7c8 (Ann Lee <ann@example.com> 1700) declare(strict_types=1);

Each line shows the first 8 characters of the commit hash and the first 30 characters of the author identity (Name <email> timestamp timezone), unpadded.

grep

Search file contents in the current HEAD tree.

pitmaster grep "function merge"
pitmaster grep -i -E "h.llo"

Output:

src/Repository.php:2257:    public function merge(string $branch, string $strategy = 'recursive'): MergeResult
src/Merge/ThreeWayMerge.php:23:    public static function merge(

Options must come before the pattern:

• -i, --ignore-case: case-insensitive matching
• -E, --extended-regexp, --regex: treat the pattern as a PCRE regular expression

Output is plain path:line:content without colors.

reflog

Show reflog entries, newest first.

# HEAD reflog (default: 10 entries)
pitmaster reflog

# Another ref, a custom limit, and a format
pitmaster reflog show refs/heads/main
pitmaster reflog -n 5
pitmaster reflog --format="%h %gs"

The default format is %gd: %gs (HEAD@{0}: commit: Add feature). Supported placeholders: %gd and %gD (selector), %gs (message), %H and %h (full and short new hash). Limits accept -n N, -nN, and --max-count N; -n 0 prints all entries.

Repositories created by pitmaster init do not record reflogs unless core.logallrefupdates is set to true in .git/config (#8), so reflog prints nothing there until it is.

refs

List all refs with their hashes.

pitmaster refs

Output:

abc123def456... refs/heads/main
789012abc345... refs/heads/feature/login
def456789012... refs/tags/v1.0.0

Hashes are printed in full.

reset

Reset HEAD to a specific commit.

# Mixed reset (HEAD + index, default)
pitmaster reset HEAD~1
pitmaster reset --mixed HEAD~1

# Soft reset (HEAD only)
pitmaster reset --soft HEAD~1

# Hard reset (HEAD + index + worktree)
pitmaster reset --hard HEAD~3

A revision is required. Output:

HEAD is now at abc1234

init

Initialize a new repository. This is the only command that does not need an existing repository.

# Initialize in the current directory
pitmaster init

# Initialize at a specific path
pitmaster init /path/to/new-project

# Create a SHA-256 repository
pitmaster init --object-format=sha256
pitmaster init /path/to/new-project --object-format=sha256

Output:

Initialized empty Pitmaster repository in /path/to/new-project/.git/

--object-format accepts sha1 (default) and sha256.

Exit codes