A coding harness, the program that runs an agent's tools, can ask Git what a command would do before making a change. --dry-run asks for a preview. --porcelain gives the harness a report it can parse and check against the task.
Preview the command
Nick Romney starts with git add -n terraform/. It lists what Git would stage in that directory. The long form, git add --dry-run terraform/, does the same thing.12
On git commit, -n means --no-verify. Git can create a commit and skip the pre-commit and commit-msg hooks. Use git commit --dry-run to preview a commit.3
What porcelain means
Git calls high-level commands such as git commit porcelain. The lower-level commands, such as git write-tree, are plumbing. As an option, --porcelain asks a command for a documented output format for scripts.4
git status --porcelain=v1 -z uses stable status codes and ends pathnames with a NUL byte, so scripts can read filenames containing spaces or newlines. Needlefish, a pull request review harness, uses git status --porcelain to check whether the reviewer changed its checkout.56
git commit --porcelain uses the status format and already implies --dry-run. Preview the commit with the options you plan to use. Include -a in the preview if the actual commit will use it to include all tracked changes.3
A commit for the manuals API
In Alder, a fictional Rails CMS, a feature flag controls whether the content API exposes manuals and their sections. The harness stages the API change and a test for the flag. An unrelated editor setting is already staged in the same checkout.
git commit --dry-run --porcelain -z --untracked-files=all
The preview returns these records. The NUL separators are shown as line breaks.
M app/api/manuals.rb
M config/editor.yml
A test/api/manuals_test.rb
?? scratch/sample.json
In the first column, M marks a staged modification and A marks a staged addition. The proposed commit would include config/editor.yml alongside the two feature files, so the harness reports that path and leaves the staging area alone. ?? marks the untracked export, which stays out of the commit.
Once only the feature files are staged, git diff --cached shows the patch for review.
Preview the push
After committing, the harness can ask Git what it would push to origin. The refspec names the local branch and the remote branch it should update.
git push --dry-run --porcelain origin \
refs/heads/manuals-api:refs/heads/manuals-api
Git reports one row per ref on stdout. The status character, the pair of ref names, and the summary are separated by tabs. In this run, * means Git would create a branch.7
* refs/heads/manuals-api:refs/heads/manuals-api [new branch]
The harness checks the exit status and matches the reported destination to the branch it meant to update. An = row means the branch is already up to date, so a successful exit can mean there was nothing to update. git push --porcelain on its own attempts a real push. --dry-run keeps the update from being sent.7
The git-wwpd script uses both flags to read the old..new range Git reports for a fast-forward. It passes the range to git log to show the commits the branch would gain.8
A dry-run push still contacts the remote, may need credentials, and can run a local hook. In a test with Git 2.55.0 and a local bare remote, the pre-push hook ran during the preview. The real push then reached a server-side pre-receive hook and was rejected. The remote branch can also move between the preview and the real push.9