1STG(1) StGit Manual STG(1)
2
6 stg - Manage stacks of patches using the Git content tracker
7
9 stg [--version | --help]
10 stg [--help <command> | <command> --help]
11 stg <command> [COMMAND OPTIONS] [ARGS]
12
14 StGit (Stacked Git) is an application that provides a convenient way to
15 maintain a patch stack on top of a Git branch:
16 • The topmost (most recent) commits of a branch are given names. Such
18 a named commit is called a patch.
19 • After making changes to the worktree, you can incorporate the
21 changes into an existing patch; this is called refreshing. You may
22 refresh any patch, not just the topmost one.
23 • You can pop a patch: temporarily putting it aside, so that the
25 patch below it becomes the topmost patch. Later you may push it
26 onto the stack again. Pushing and popping can be used to reorder
27 patches.
28 • You can easily rebase your patch stack on top of any other Git
30 commit. (The base of a patch stack is the most recent Git commit
31 that is not an StGit patch.) For example, if you started making
32 patches on top of someone else’s branch, and that person publishes
33 an updated branch, you can take all your patches and apply them on
34 top of the updated branch.
35 • As you would expect, changing what is below a patch can cause that
37 patch to no longer apply cleanly — this can occur when you reorder
38 patches, rebase patches, or refresh a non-topmost patch. StGit uses
39 Git’s rename-aware three-way merge capability to automatically fix
40 up what it can; if it still fails, it lets you manually resolve the
41 conflict just like you would resolve a merge conflict in Git.
42 • The patch stack is just some extra metadata attached to regular Git
44 commits, so you can continue to use most Git tools along with
45 StGit.
46 Typical uses
48 Tracking branch
49 Tracking changes from a remote branch, while maintaining local
50 modifications against that branch, possibly with the intent of
51 sending some patches upstream. You can modify your patch stack as
52 much as you want, and when your patches are finally accepted
53 upstream, the permanent recorded Git history will contain just the
54 final sequence of patches, and not the messy sequence of edits that
55 produced them.
56 Commands of interest in this workflow are e.g. rebase and mail.
58 Development branch
60 Even if you have no "upstream" to send patches to, you can use
61 StGit as a convenient way to modify the recent history of a Git
62 branch. For example, instead of first committing change A, then
63 change B, and then A2 to fix A because it wasn’t quite right, you
64 could incorporate the fix directly into A. This way of working
65 results in a much more readable Git history than if you had
66 immortalized every misstep you made on your way to the right
67 solution.
68 Commands of interest in this workflow are e.g. uncommit, which can
70 be used to move the patch stack base downwards — i.e., turn Git
71 commits into StGit patches after the fact — and commit, its
72 inverse.
73 For more information, see the tutorial[1].
75 Specifying patches
77 Many StGit commands take references to StGit patches as arguments.
78 Patches in the stack are identified with short names, each of which
79 must be unique in the stack.
80 Patches in the current branch are simply referred to by their name.
82 Some commands allow you to specify a patch in another branch of the
83 repository; this is done by prefixing the patch name with the branch
84 name and a colon (e.g. otherbranch:thatpatch).
85 Specifying commits
87 Some StGit commands take Git commits as arguments. StGit accepts all
88 commit expressions that Git does; and in addition, a patch name
89 (optionally prefixed by a branch name and a colon) is allowed in this
90 context. The usual Git modifiers ^ and ~ are also allowed; e.g.,
91 abranch:apatch~2 is the grandparent of the commit that is the patch
92 apatch on branch abranch.
93 Instead of a patch name, you can say {base} to refer to the stack base
95 (the commit just below the bottommost patch); so, abranch:{base} is the
96 base of the stack in branch abranch.
97 If you need to pass a given StGit reference to a Git command, stg-id(1)
99 will convert it to a Git commit id for you.
100
102 The following generic option flags are available. Additional options
103 are available for (and documented with) the different subcommands.
104 --version
106 Prints the StGit version, as well as version of other components
107 used, such as Git and Python.
108 --help
110 Prints the synopsis and a list of all subcommands. If an StGit
111 subcommand is given, prints the synposis for that subcommand.
112
114 We divide StGit commands in thematic groups, according to the primary
115 type of object they create or change.
116 Here is a short description of each command. A more detailed
118 description is available in individual command manpages. Those manpages
119 are named stg-<command>(1).
120
122 StGit uses the same configuration mechanism as Git. See git(7) for more
123 details.
124
126 A number of StGit commands make use of template files to provide useful
127 default texts to be edited by the user. These <name>.tmpl template
128 files are searched in the following directories:
129 1. $GITDIR/ (in practice, the .git/ directory in your repository)
131 2. $HOME/.stgit/templates/
133 3. /usr/share/stgit/templates/
135
137 1. tutorial
138 https://stacked-git.github.io/guides/tutorial
139StGit 1.4 01/22/2022 STG(1)