git sh-setup

Sourced by Git's shell-script subcommands.

🎯 What & why

Internal shell setup library sourced by Git's shell-built subcommands. Provides the standard helper functions every porcelain shell script depends on.

🧠 Mental model

A 'standard library' for git's .sh commands. Source it and you get say, die, cd_to_toplevel, require_work_tree, reflog action setting, GIT_DIR resolution, and all the boilerplate the C plumbing usually handles.

🛠️ Synopsis

. "$(git --exec-path)/git-sh-setup"

# Then call helpers like:
require_work_tree
cd_to_toplevel
set_reflog_action "myscript"
say "doing the thing"
die "fatal: cannot proceed"

🎚️ Switches & options

Flag	What it does
`(sourced) say`	Print to stdout unless `GIT_QUIET` is set
`(sourced) die`	Print to stderr and exit 128
`(sourced) cd_to_toplevel`	chdir to the worktree root
`(sourced) require_work_tree`	Abort if not inside a working tree
`(sourced) require_clean_work_tree`	Abort on uncommitted changes (also takes 'rebase'/'merge' verb)
`(sourced) set_reflog_action`	Set GIT_REFLOG_ACTION so reflog entries name your script
`(sourced) git_pager`	Pipe through the configured pager

💡 Use cases

Reading it as a tour of how Git's shell-built porcelain is structured
Writing a custom git-foo shell extension that should feel native
Debugging why a stock script aborted with 'fatal: this operation must be run in a work tree'
Making sure your custom commands name themselves in the reflog correctly

🧪 Examples

Bootstrap a custom git subcommand

. "$(git --exec-path)/git-sh-setup"

Refuse to run with a dirty tree

require_clean_work_tree rebase 'commit or stash first'

Move to the worktree root

cd_to_toplevel

Tag your reflog entries

set_reflog_action 'git foo'

🎓 Recommendations

Always call set_reflog_action early - reflog spam without a clear actor name is a debugging nightmare.
Prefer die over exit 1; it follows Git's convention of exit code 128 for fatal errors.
Read this file once - it's the cleanest documentation of Git's internal shell conventions you'll find.

🪤 Common pitfalls

It's not a public API; helper signatures and behavior have changed quietly across releases.
require_work_tree does not check for index lock or repo health - just that GIT_DIR resolves to a working tree.
Sourcing it twice can clobber options you set in between (USAGE, OPTIONS_SPEC, etc.).

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.