Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

The recommended way to configure spr is to run spr init, rather than setting config values manually. You can rerun spr init to update config at any time.

spr uses the following Git configuration values:

config keyCLI flagdescriptiondefault1default in spr init2
auth.github.token3--auth-token4The token for accessing GitHub (github.com); for GitHub Enterprise, auth.github.HOST.tokenobtained by logging in with GitHub, or entered (GitHub Enterprise)
target--target5Where pull requests get merged: forge, repository and branch, e.g. github:owner/repo:master6the repository that the origin remote points to, and its default branch
branchPrefix--branch-prefixString used to prefix autogenerated names of pull request branchesspr/GITHUB_USERNAME/
requireApprovalIf true, spr land will refuse to land a pull request that is not acceptedfalsenot set
mergeMethodHow pull requests are merged: squash or merge7squashnot set
stackingModeHow pull requests of stacked commits are set up: base-branches, chain or github-stack8base-branches with squash, chain with mergenot set
useCommitTitleForInitialCommitIf true, uses the actual commit title for the initial PR commit message. If false, uses [𝘀𝗽𝗿] initial version.falsenot set
sprIdsIf true, spr diff and spr patch give every local commit an ID (Spr-Id trailer); otherwise only with --spr-id9falsenot set

  • The config keys are all in the spr section; for example, spr.mergeMethod.

  • Values passed on the command line take precedence over values set in Git configuration.

  • Values are read from Git configuration as if by git config --get, and thus follow its order of precedence in reading from local and global config files. See the git-config docs for details.

  • spr init writes configured values into .git/config in the local repo. (It must be run inside a Git repo.)

  1. Value used by spr if not set in configuration. ↩

  2. Value suggested by spr init if not previously configured. ↩

  3. The token for a forge and host: auth.github.token for github.com, auth.github.HOST.token for GitHub Enterprise on HOST (e.g. spr.auth.github.ghe.example.com.token; the host in lower case, with the port if it has one). Set it in the repository, or globally for all repositories (git config --global …). Before spr supported other hosts, the token was githubAuthToken. spr still reads it as the token for github.com if auth.github.token isn’t set, but it’s deprecated and will be removed in a future version: spr shows a note on how to replace it. spr init replaces it in the repository’s .git/config. ↩

  4. For the forge and host of the target. Be careful using this: your auth token will be in your shell history. The deprecated option --github-auth-token still works. ↩

  5. --target takes a full target, or a branch name alone for a branch in the repository of target. It applies to commits without a Spr-Target trailer, and spr diff gives commits for other targets than target such a trailer. See Target Another Branch. The deprecated options --github-repository (owner/repo) and --github-master-branch still work, overriding the repository or the branch of target. ↩

  6. The notation is FORGE:REPOSITORY:BRANCH, where the repository may start with //HOST/ for another host than the forge’s public one. For now, spr supports only GitHub (github:), with the repository as owner/repo: on github.com (github:owner/repo:main), or on GitHub Enterprise (github://ghe.example.com/owner/repo:main; see GitHub Enterprise). The branch is everything after the last colon (branch names can’t contain colons), e.g. github:acme/project:release/1.2. Before target, spr had two options, githubRepository (owner/repo) and githubMasterBranch (default: master). spr still reads them if target isn’t set, but they’re deprecated and will be removed in a future version: spr shows a note on how to replace them. spr init replaces them in the repository’s .git/config (and keeps a branch configured there). ↩

  7. spr land squash-merges pull requests, or merges them with a merge commit. The setting also records the convention of the repository, as pull requests may be merged in the GitHub UI, too. See Choose a Merge Method and Stacking Mode. ↩

  8. base-branches: the pull request targets a synthetic base branch created by spr. chain: the pull request targets the pull request branch of the parent commit. github-stack: like chain, and the pull requests are linked as a stack on GitHub (GitHub’s stacked pull requests feature, in public preview). The combination of mergeMethod merge and stackingMode base-branches is not allowed. See Choose a Merge Method and Stacking Mode for the trade-offs. ↩

  9. The ID identifies a local commit and its pull request across amends and rebases, like Gerrit’s Change-Id. It only appears in local commit messages — not in pull requests, nor in the commits that land. The setting only controls whether IDs are added automatically: commits that have an ID keep it either way. See Identify Commits with Spr-Ids. ↩