stg - Manage stacks of patches using the Git content tracker
stg [--version | --help]
stg [--help <command> | <command> --help]
stg <command> [COMMAND OPTIONS] [ARGS]
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.
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.
Many StGit commands take references to StGit patches as arguments.
Patches in the stack are identified with short names, each of which must be
unique in the stack.
Patches in the current branch are simply referred to by their
name. 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).
Some StGit commands take Git commits as arguments. StGit accepts
all commit expressions that Git does; and in addition, a patch name
(optionally prefixed by a branch name and a colon) is allowed in this
context. The usual Git modifiers ^ and ~ are also allowed; e.g.,
abranch:apatch~2 is the grandparent of the commit that is the patch apatch
on branch abranch.
Instead of a patch name, you can say {base} to refer to the stack
base (the commit just below the bottommost patch); so, abranch:{base} is the
base of the stack in branch abranch.
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.
The following generic option flags are available. Additional
options are available for (and documented with) the different
subcommands.
--version
Prints the StGit version, as well as version of other
components used, such as Git and Python.
--help
Prints the synopsis and a list of all subcommands. If an
StGit subcommand is given, prints the synposis for that subcommand.
We divide StGit commands in thematic groups, according to the
primary type of object they create or change.
Here is a short description of each command. A more detailed
description is available in individual command manpages. Those manpages are
named stg-<command>(1).
stg-clone(1)
Make a local clone of a remote repository
stg-id(1)
Print the git hash value of a StGit reference
StGit uses the same configuration mechanism as Git. See
git(7) for more details.
A number of StGit commands make use of template files to provide
useful default texts to be edited by the user. These <name>.tmpl
template files are searched in the following directories:
1.$GITDIR/ (in practice, the .git/ directory in your
repository)
2.$HOME/.stgit/templates/
3./usr/share/stgit/templates/
- 1.
- the tutorial
[set
$man.base.url.for.relative.links]/tutorial.html