Skip to content

CLI configuration

v0.4.0

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.

# Set an option for current user$ git config --global <key> <value># Set an option for current repository$ git config --local <key> <value>
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

v0.5.0

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:

  • true
  • false (default)

spice.branchPrompt.sort

v0.11.0

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 date
  • refname: 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

v0.5.0

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.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

v0.9.0

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

Unreleased

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

v0.9.0

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:

  • true
  • false (default)

spice.log.crFormat

Unreleased

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.log.pushStatusFormat

Unreleased

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 status
  • false: 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

v0.10.0

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.listTemplatesTimeout

v0.8.0

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 comments
  • false: don't post or update navigation comments
  • multiple: post or update navigation comments only for stacks with at least two CRs

spice.submit.publish

v0.5.0

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

v0.8.0

Whether submission commands ( gs branch submit and friends) should open a web browser with submitted CRs.

Accepted values:

  • true
  • false (default)