Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git sh-setup helper library

Reference for git-sh-setup: the shell library for writing Git commands in sh, with die, usage, require_work_tree, cd_to_toplevel and require_clean_work_tree.

git-sh-setup is not a command you run. It is a small library of shell functions that you load with the . (dot) command at the top of a script. Many of Git's own scripts (git-bisect, git-rebase helpers, git-stash in its early days) started with it. It finds the repository, sets a few variables, and gives you functions for the chores every Git script repeats: failing with a message, checking that you are inside a work tree, and changing to its top.

A script named git-hello placed on your PATH becomes git hello, so this library is the shortest path from "a shell snippet" to "a real Git subcommand". It is documented for use in scripts, but it targets POSIX sh, so keep your own code portable too.

Terminal
#!/bin/sh
. "$(git --exec-path)/git-sh-setup"

Try it

Bash A tiny Git subcommand

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash die, clean checks and the top of the tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
SUBDIRECTORY_OK=Yes        # optional
USAGE='<arguments>'        # optional one-line usage
LONG_USAGE='...'           # optional longer help
OPTIONS_SPEC='...'         # optional: use git rev-parse --parseopt
. "$(git --exec-path)/git-sh-setup"

Set these variables before sourcing the library.

Name Description
SUBDIRECTORY_OK If set, the script may run from a subdirectory. Otherwise it stops with "You need to run this command from the toplevel of the working tree." when started below the top.
USAGE, LONG_USAGE Texts shown by usage. The library prefixes the command name for you.
OPTIONS_SPEC If set, the library runs git rev-parse --parseopt on "$@" so options are parsed and help is generated for you.
NONGIT_OK If set, the script may run outside a repository; otherwise it dies with "not a git repository".

Functions:

Name Description
die <message> Print the message to standard error and exit with status 1.
usage Print the usage text and exit with status 1.
require_work_tree Die if there is no work tree (for example in a bare repository).
require_work_tree_exists Die only if the work tree directory is missing.
cd_to_toplevel Change to the top-level directory of the work tree.
require_clean_work_tree <action> [<hint>] Die with a message mentioning the action if there are unstaged changes or uncommitted staged changes (untracked files do not count).
is_bare_repository Print true or false.
git_editor Run the user's configured editor on a file.
set_reflog_action <label> Set GIT_REFLOG_ACTION unless the caller already did.

Variables set for you: GIT_DIR holds the path to the repository, so scripts can look at files inside it.

Usage notes

  • Quote the path. Always write . "$(git --exec-path)/git-sh-setup". The old form . git-sh-setup works only when the exec path happens to be on PATH, which is true when Git runs your script but not when you test it by hand.
  • Start with SUBDIRECTORY_OK unless the script really needs the top directory. If you need it, call cd_to_toplevel instead and allow subdirectories.
  • Messages go to stderr, exit status is 1. die and usage do not return, so no || exit is needed after them.
  • Not a stable public API for every function. The documented ones above are safe to use. Older helpers that appear in the file can change between releases; do not rely on them.
  • Dirty checks. require_clean_work_tree is what git pull --rebase style scripts use. It refreshes the index first, so a mere timestamp change does not look like an edit.
  • Prefer a real language for larger tools. Shell scripts are fine for small glue; for anything with many options or error cases, consider Python or a compiled language, and use plumbing commands such as git rev-parse for the same repository checks.
  • Aliases are an alternative. A one-line job rarely needs a script: git config alias.hello '!echo hi' runs a shell command directly (see Aliases).