STG(1)

📦
version 2.7.0 · 9 versions
, in opensuse-leap 16.0

💖 STG(1) — Manage stacks of patches using the Git content tracker 💖

okay bestie, welcome to the StGit Manual — this is the page for stg, and we’re gonna make it make sense. No cap.

🎀 NAME 🎀

stg — Manage stacks of patches using the Git content tracker

✨ SYNOPSIS ✨

stg [OPTIONS] <command> [...]
stg [OPTIONS] <-h|--help>
stg --version

🦋 DESCRIPTION 🦋

StGit (Stacked Git) is an application that provides a convenient way to maintain a patch stack on top of a Git branch:

  • The topmost (most recent) commits of a branch are given names. Such a named commit is called a patch.
  • After making changes to the worktree, you can incorporate the changes into an existing patch; this is called refreshing. You may refresh any patch, not just the topmost one.
  • You can pop a patch: temporarily putting it aside, so that the patch below it becomes the topmost patch. Later you may push it onto the stack again. Pushing and popping can be used to reorder patches.
  • You can easily rebase your patch stack on top of any other Git commit. (The base of a patch stack is the most recent Git commit that is not an StGit patch.) For example, if you started making patches on top of someone else’s branch, and that person publishes an updated branch, you can take all your patches and apply them on top of the updated branch.
  • As you would expect, changing what is below a patch can cause that patch to no longer apply cleanly — this can occur when you reorder patches, rebase patches, or refresh a non-topmost patch. StGit uses Git’s rename-aware three-way merge capability to automatically fix up what it can; if it still fails, it lets you manually resolve the conflict just like you would resolve a merge conflict in Git.
  • The patch stack is just some extra metadata attached to regular Git commits, so you can continue to use most Git tools along with StGit.

🌸 Typical uses 🌸

🎀 Tracking branch

Tracking changes from a remote branch, while maintaining local modifications against that branch, possibly with the intent of sending some patches upstream. You can modify your patch stack as much as you want, and when your patches are finally accepted upstream, the permanent recorded Git history will contain just the final sequence of patches, and not the messy sequence of edits that produced them.

Commands of interest in this workflow are e.g. rebase and mail.

🎀 Development branch

Even if you have no "upstream" to send patches to, you can use StGit as a convenient way to modify the recent history of a Git branch. For example, instead of first committing change A, then change B, and then A2 to fix A because it wasn’t quite right, you could incorporate the fix directly into A. This way of working results in a much more readable Git history than if you had immortalized every misstep you made on your way to the right solution.

Commands of interest in this workflow are e.g. uncommit, which can be used to move the patch stack base downwards — i.e., turn Git commits into StGit patches after the fact — and commit, its inverse.

For more information, see the tutorial[1].

🦋 Specifying patches 🦋

Most StGit commands have patch arguments. Patches in the stack may be specified in a variety of ways. A patch in the current branch may simply be referred to by its name, or, alternatively, be located by a relative offset from the topmost patch (e.g. +3), as an absolute index into the stack (e.g. 7), or as an offset from the last visible patch (e.g. ^1).

Some commands allow you to specify a patch in another branch of the repository; this is done by prefixing the patch name with the branch name and a colon (e.g. otherbranch:thatpatch).

Commands that take multiple patch arguments may be supplied with patch ranges of the form patch1..patchN as an alternative to specifying each patch individually. For example, stg delete p0..p4 would be equivalent to stg delete p0 p1 p2 p3 p4. Patch ranges may be open on either or both ends. For example, stg delete ..p2 would delete the first applied patch up to and including patch p2. Alternatively, stg delete p2.. would delete patch p2 up to and including the topmost applied patch. And stg delete .. would delete all applied patches.

The complete syntax for locating patches follows:

  • <patchname>, e.g. patch — The name of a patch.
  • @ — Refers to the topmost applied patch, or the base of the stack if no patches are applied.
  • [<patchname>]~[<n>], e.g. ~2, patch~, patch~3 — The <n>th previous patch from the named patch. If <patchname> is not supplied, @ is implied. A single ~ represents the first previous patch. Multiple ~ may be specified, e.g. patch~~~ is the same as patch~3. This is similar to git’s revision syntax where <rev>~[<n>] means the <n>th ancestor commit from <rev> following first parents.
  • [<patchname>]+[<n>], e.g. +, +3, patch+, patch+3 — The <n>th next patch from the named patch. If <patchname> is not supplied, @ is implied. A single + represents the next patch in the series. Multiple + may be specified, e.g. patch+++ is the same as patch+3.
  • -[<n>], e.g. -3, - — References the <n>th previously applied patch. This is similar to ~<n>, except it is only valid without a patch name prefix. Note that certain commands with other options taking numeric values may require escaping - with \-, e.g. \-10.
  • <n>, e.g. 3 — The patch at absolute index <n> in the stack. This is a zero-based index, so 0 refers to the bottommost patch in the stack.
  • ^[<n>], e.g. ^, ^3 — The patch at offset <n> from the last visible patch in the stack. This is a zero-based offset, so ^0 refers to the last visible patch in the stack, which is equivalent to just ^. Negative values of <n> are allowed and refer to hidden patches which are after the last visible patch in the stack.
  • {base}+[<n>], e.g. {base}+, {base}+3 — The patch at offset <n> from the stack’s base commit. Since the stack base is not a commit, a positive offset is required.

Take note that numeric patch locations of the form <n>, -<n>, and +<n>, e.g. 3, -3, or +3 are also valid patch names. I.e. it is possible (but not recommended) to name a patch, for example, "-3". In the case where a patch name could also be interpreted as a numeric index or offset, the literal patch name will take precedence when resolving the patch location.

💜 Specifying commits 💜

Some StGit commands take Git commits as arguments. StGit accepts all revision specifications that Git does (see gitrevisions(7)); and additionally, the patch specifiers from above. The usual Git modifiers, including ^, are also allowed; e.g. some-branch:a-patch^^ refers to the grandparent of the commit that is patch a-patch on branch some-branch.

If you need to pass a given StGit reference to a Git command, stg-id(1) will convert it to a Git commit id for you.

👑 OPTIONS 👑

The following generic option flags are available. Additional options are available for (and documented with) the different subcommands.

  • --version — Print version information
  • --help — Print help information.
  • -C — Run as if stg was started in <path> instead of the current working directory. When multiple -C options are given, each subsequent non-absolute -C <path> is interpreted relative to the preceding -C <path>.

This option affects arguments that expect path names or path specs in that their interpretations of the path names would be made relative to the working directory caused by the -C option.

  • --color <when> — Specify when to colorize the output.

auto (the default) enables colored output only when outputting to a terminal or TTY. The NO_COLOR environment variable is respected.

always and never unconditionally enable/disable colored output, respectively.

ansi forces color to be output using ANSI escape sequences, even in a Windows console.

🛠️ STGIT COMMANDS 🛠️

okay so real talk: StGit has a lot of commands, and we sort them into thematic little cliques based on the primary type of object they create or change. it's giving organized. it's giving ✨taxonomy✨.

here's the quick rundown of every single one. want the full tea on any of them? each command has its own manpage with all the details — those are named stg-<command>(1). cute, right? 🎀

🔍 Patch Inspection 🔍

the read-only girlies. they just look at stuff and report back. no notes. 💅

  • stg-diff(1) — show you a diff
  • stg-files(1) — show you which files a patch modified
  • stg-id(1) — print the git hash of a StGit revision
  • stg-log(1) — display the stack changelog, or optionally clear it if that's the vibe
  • stg-name(1) — print the patch name of a StGit revision
  • stg-show(1) — show the patch commits

🎨 Patch Manipulation 🎨

this is where you actually do things to patches. main character energy fr fr.

📚 Stack Inspection 📚

again with the looking, but now it's the whole stack bestie. very demure, very observant. 🦋

🔥 Stack Manipulation 🔥

the heavy hitters. this is the section that ate and left no crumbs. 😭

🧚 Administration 🧚

the backstage crew keeping the whole production running. lowkey iconic. 👑

⚙️ CONFIGURATION MECHANISM ⚙️

Okay bestie, here's the tea: StGit doesn't reinvent the wheel when it comes to config — it uses the exact same configuration mechanism as Git. So all your Git config muscle memory? Slay, it just works. Peep git-config(1) for the full deets. 💅

💖 Variables 💖

  • branch.<name>.stgit.autostash, branch.<name>.stgit.fetchcmd, branch.<name>.stgit.pull-policy, branch.<name>.stgit.pullcmd, branch.<name>.stgit.rebasecmd — these are the branch-specific versions of the config values, and they take precedence over the corresponding non-branch specific ones (scroll down, they're all listed below 👇).
  • branch.<name>.stgit.parentbranch — tells you the parent branch of a branch that's got a StGit stack. Heads up: this one is set by stg-branch(1) when you create or clone branches, and it's not typically set by the user. Where it matters: stg-pull(1) reads it when stgit.pull-policy is either rebase or fetch-rebase, so it can figure out the target of the rebase. 🎯
  • stgit.alias.* — command aliases for stg, periodt. So like, after you define stgit.alias.list = series -d, running stg list is literally equivalent to stg series -d. Arguments get split by spaces, and the usual shell quoting and escaping is supported — a quote pair or a backslash may be used to quote them.

And here's the iconic part: if the alias expansion is prefixed with an exclamation point (!), it gets treated as a shell command. Example: defining stgit.alias.outgoing = !git log @{u} means running stg outgoing is equivalent to running the shell command git log @{u}. Note that shell commands will be executed from the top-level directory of the working tree, which may not necessarily be the current directory. GIT_PREFIX is set as returned by running git rev-parse --show-prefix from the original current directory. See git-rev-parse(1). 🐚

Aliases that would hide existing StGit commands are ignored. 🙈
  • stgit.autoimerge — set it to true and if conflicts pop off when pushing a patch, git-mergetool(1) gets automatically run to attempt to resolve them. Auto-rescue mode activated. 🦸‍♀️
  • stgit.autosign — automatically adds a signoff trailer to commit messages for new patches created with stg-new(1) or stg-import(1). Here's the trick: the value of this config variable is used as the key of the trailer, so it should be set to something like Signed-off-by. 💫
  • stgit.autostash — when running stg-rebase(1), if any modified files are found in the working tree, a temporary stash is created with git-stash(1) before the operation begins, and it gets applied after the operation completes. Your uncommitted work said "not today" and got tucked away safely. 🧺
  • stgit.diff-opts — options passed through to git diff-tree for stg-diff(1), stg-export(1), stg-patches(1), and stg-show(1). You can specify multiple space-separated options. See git-diff-tree(1) for info about the various available options. ✨
  • stgit.edit.verbose — set to true and the patch's diff gets shown when you're interactively editing a patch description with, for example, stg-edit(1). Context is giving main character energy. 👑
  • stgit.editor — commands like stg-edit(1) and stg-new(1) open an editor to edit the patch description and commit message. The editor set by this variable is launched when the GIT_EDITOR environment variable is not set. And get this: this variable takes precedence over the core.editor configuration variable as well as the VISUAL and EDITOR environment variables. It's the top of the editor food chain, fr fr. 🧚
  • stgit.fetchcmd — the command specified here gets run by stg-pull(1) to fetch from the remote repository when stgit.pull-policy is fetch-rebase. When it's not set, the default command is git fetch. 📡
  • stgit.gpgsign — a boolean specifying whether StGit stack metadata commits should be GPG signed.
N.B. Set commit.gpgsign to determine whether patch commits themselves are GPG signed. See git-config(1) for more information about commit.gpgsign. 🔐
  • stgit.import.message-id — set to true and it creates a Message-ID: trailer in the patch description of patches imported from email using stg-import(1). 📬
  • stgit.infer-commands — when set to true, StGit commands and aliases may be invoked using any unambiguous prefix of their names. Example incoming: stg ser runs stg series. Exact command and alias names always take precedence over prefixes. Prefixes are not accepted in alias definitions — aliases must name their StGit command exactly. Defaults to false. 🧠
N.B. whether a prefix is unambiguous depends on the set of defined aliases as well as the set of StGit commands. Defining a new alias, or upgrading to a version of StGit with new commands, may cause a previously unambiguous prefix to become ambiguous. Explicit aliases (see stgit.alias.*) are a more stable alternative for abbreviating commonly used commands. ⚠️
  • stgit.keepoptimized — set to true and, after pulling changes with stg-pull(1), the repository's object database will be optimized by running git-repack(1). Glow-up for your object database. 🔥
  • stgit.namelength — an integer used to determine the maximum length, in characters, of automatically generated patch names. The default value is 30. This option does not affect user-specified patch names. Setting it to a value less than or equal to 0 will allow automatically generated patch names of unlimited length. 📏

Automatically generated patch names are truncated at word boundaries less than or equal to the value of stgit.namelength. As a result, patch names will typically not be truncated at exactly this number of characters. It's also possible for automatically generated patch names to be longer than this value if a work boundary cannot be found within this bound, or if additional characters need to be added to the patch name to make it unique. So like, it's a vibe guideline, not a hard wall. 😌

  • stgit.pick.expose-format — the format of the commit message for patches picked using the --expose option with stg-pick(1). The value of this option is as may be specified to the --pretty option of git-show(1). The default is format:%B%n(imported from commit %H). 🎀
  • stgit.pull-policy — the policy used by stg-pull(1) for pulling changes from a remote repository. Valid values include:
    • pull — the default — uses git-pull(1) or stgit.pullcmd, if set, to pull changes from the remote repository.
    • rebase — uses git-reset(1) or stgit.rebasecmd, if set, to rebase the patch stack before reapplying patches.
    • fetch-rebase — first fetches commits from the remote repository using git-fetch(1) or stgit.fetchcmd, if set, before performing the rebase as described above.
  • stgit.pullcmd — the command to be run by stg-pull(1) to pull changes from the remote repository when stgit.pull-policy is pull (the default). The default value is git pull. 🚀
  • stgit.push.allow-conflicts — a boolean specifying whether stg-push(1) and other commands that push patches will push patches that may result in merge conflicts. The default is true, which means a patch with conflicts will be pushed, and if the conflicts can't be automatically resolved, the operation will stop with the conflicts left to be resolved manually. 😭

When set to false, a patch that would have merge conflicts will not be pushed, thus leaving the stack on the last patch that could be pushed without conflicts.

This configuration variable may be overridden on the command line with either --conflicts[=allow] or --conflicts=disallow. 🫶

N.B.: stgit.autoimerge only has an affect when push conflicts are allowed. 💀
  • stgit.rebasecmd — the command to be run by stg-pull(1) to set the new stack base when stgit.pull-policy is either rebase or fetch-rebase. The default is git reset --hard. 🪄
  • stgit.refreshsubmodules — a boolean specifying whether stg-refresh(1) includes submodules in patch content. This value may be overridden by the --submodules or --no-submodules option to stg-refresh(1). By default, submodule content is not included in patch content. 🧩
  • stgit.shortnr — the number of patches listed by stg-series(1) when the -s/--short option is specified. Defaults to 5. ✋

🎀 TEMPLATES 🎀

A bunch of StGit commands make use of template files to hand you useful default texts that you then get to edit. These <name>.tmpl template files get searched in the following directories, in this order:

  1. $GITDIR/ (in practice, the .git/ directory in your repository)
  2. $XDG_CONFIG_HOME/stgit/templates/
  3. $HOME/.stgit/templates/

First one wins, so put your personal templates where they belong bestie. 🌸

📝 NOTES 📝

  1. tutorial — https://stacked-git.github.io/guides/tutorial

And that's the whole page, bestie!! 🦋 You just read the entire STG(1) manpage and honestly? Iconic behavior. This beauty is StGit 2.7.0, dated 10/17/2026 — go forth and stack those patches, you absolute legend. 💜✨🌈

📦 where this page comes from