CLI configuration¶
The behavior of git-spice can be customized with git config.
Configuration options may be set at the user level with the --global flag,
or at the repository level with the --local flag.
What about --system and --worktree?
All configuration levels supported by git config are allowed,
although --system and --worktree are less commonly used.
Use --worktree to override repository-level settings
for a specific git-worktree.
Available options¶
spice.branchCheckout.showUntracked¶
When running gs branch checkout without any arguments, git-spice presents a prompt to select a branch to checkout. This option controls whether untracked branches are shown in the prompt.
Accepted values:
truefalse(default)
spice.branchCheckout.trackUntrackedPrompt¶
If gs branch checkout is used to checkout a branch that is not tracked, git-spice will present a prompt like the following to begin tracking it:
This option allows you to disable the prompt if you frequently checkout untracked branches and don't want to be prompted to track them.
Accepted values:
true(default)false
spice.branchPrompt.sort¶
Commands like gs branch checkout, gs branch onto, etc., that require a branch name will present an interactive prompt to select the branch when one isn't provided.
This option controls the sort order of branches in the prompt. It is git-spice's equivalent of git's branch.sort configuration.
Commonly used values are:
committerdate: sort by commit daterefname: sort by branch name (default)authordate: sort by author date
See git-for-each-ref(1) field names for a full list of available fields.
Prefix a field name with - to sort in descending order.
For example, use -committerdate to sort by commit date in descending order.
spice.branchCreate.commit¶
Whether gs branch create should commit staged changes to the new branch.
Set this to false to default to creating new branches without committing,
and use the --commit flag to commit changes when needed.
true(default)false
spice.branchCreate.prefix¶
If set, the prefix will be prepended to the name of every branch created with gs branch create.
Commonly used values are:
<name>/: the committer's name<username>/: the committer's username
spice.forge.github.apiUrl¶
URL at which the GitHub API is available.
Defaults to $GITHUB_API_URL if set,
or computed from the GitHub URL if not set.
See also: GitHub Enterprise.
spice.forge.github.url¶
URL of the GitHub instance used for GitHub requests.
Defaults to $GITHUB_URL if set, or https://github.com otherwise.
See also: GitHub Enterprise.
spice.forge.gitlab.url¶
URL of the GitLab instance used for GitLab requests.
Defaults to $GITLAB_URL if set, or https://gitlab.com otherwise.
See also GitLab Self-Hosted.
spice.forge.gitlab.apiUrl¶
URL at which the GitLab API is available.
Defaults to $GITLAB_API_URL if set, or the GitLab URL otherwise.
See also GitLab Self-Hosted.
spice.forge.gitlab.oauth.clientID¶
Client ID for OAuth authentication with GitLab.
Defaults to git-spice's built-in Client ID (valid only for https://gitlab.com)
or $GITLAB_OAUTH_CLIENT_ID if set.
For Self-Hosted GitLab instances, you must set this value to a custom Client ID.
See also GitLab Self-Hosted.
spice.log.all¶
Whether gs log short and gs log long should show all stacks by default, instead of showing just the current stack.
Accepted values:
truefalse(default)
spice.log.crFormat¶
Whether gs log short and gs log long should show the CR URL or the ID next to any remote branches.
Accepted values:
"url": show the CR URL"id": (default) show the CR ID
spice.logShort.crFormat¶
Override for gs log short to control how change requests are displayed.
If not set, falls back to spice.log.crFormat.
Accepted values:
"url": show the CR URL"id": show the CR ID
spice.logLong.crFormat¶
Override for gs log long to control how change requests are displayed.
If not set, falls back to spice.log.crFormat.
Accepted values:
"url": show the CR URL"id": show the CR ID
spice.log.pushStatusFormat¶
Whether gs log short and gs log long should show whether the branch is in sync with its pushed counterpart.
Accepted values:
true(default): show the push statusfalse: don't show the push status"aheadBehind": show the number of outgoing and incoming commits in the form⇡1⇣2, where⇡indicates outgoing commits and⇣indicates incoming commits
spice.rebaseContinue.edit¶
Whether gs rebase continue should open an editor to modify the commit message when continuing after resolving a rebase conflict.
If set to false, you can opt in to opening the editor with the --edit flag.
Accepted values:
true(default)false
spice.submit.draft¶
Unreleased
Default value for the --draft/--no-draft flag when creating new change
requests with gs branch submit and friends.
This option affects both interactive and non-interactive modes:
- In non-interactive mode, setting this value to true
will cause git-spice to assume
--draftwhen creating new change requests. - In interactive mode, this value is used as the default for the prompt asking whether to create the change request as a draft.
Accepted values:
true: create CRs as drafts by defaultfalse(default): create CRs as ready for review by default
spice.submit.listTemplatesTimeout¶
Maximum duration that gs branch submit will wait to receive a list of available CR templates from the forge. If the timeout is reached, the command will proceed without a template.
Value must be a duration string such as 5s, 1m, 1h, etc.
Defaults to 1s.
Bump this value if you see warnings like any of the following:
WRN Failed to cache templates err="cache templates: write object: hash-object: signal: killed"
WRN Could not list change templates error="list templates: Post \"https://api.github.com/graphql\": context deadline exceeded"
Set to 0 to disable the timeout completely.
spice.submit.navigationComment¶
Specifies whether CR submission commands ( gs branch submit and friends) should post or update a navigation comment to the CR.
Accepted values:
true(default): always post or update navigation commentsfalse: don't post or update navigation commentsmultiple: post or update navigation comments only for stacks with at least two CRs
spice.submit.publish¶
Whether submission commands ( gs branch submit and friends) should publish a CR to the forge.
If this is set to false, submit commands will push branches,
but not create CRs.
In that case, the --publish flag will opt-in to creating CRs
on a case-by-case basis.
Accepted values:
true(default)false
spice.submit.web¶
Whether submission commands ( gs branch submit and friends) should open a web browser with submitted CRs.
Unreleased If set to created,
git-spice will open the web browser only for newly created CRs,
and not for existing ones that were updated.
Accepted values:
truefalse(default)created(Unreleased)