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
19 a named commit is called a patch.
20 · After making changes to the worktree, you can incorporate the
22 changes into an existing patch; this is called refreshing. You may
23 refresh any patch, not just the topmost one.
24 · You can pop a patch: temporarily putting it aside, so that the
26 patch below it becomes the topmost patch. Later you may push it
27 onto the stack again. Pushing and popping can be used to reorder
28 patches.
29 · You can easily rebase your patch stack on top of any other Git
31 commit. (The base of a patch stack is the most recent Git commit
32 that is not an StGit patch.) For example, if you started making
33 patches on top of someone else’s branch, and that person publishes
34 an updated branch, you can take all your patches and apply them on
35 top of the updated branch.
36 · As you would expect, changing what is below a patch can cause that
38 patch to no longer apply cleanly — this can occur when you reorder
39 patches, rebase patches, or refresh a non-topmost patch. StGit uses
40 Git’s rename-aware three-way merge capability to automatically fix
41 up what it can; if it still fails, it lets you manually resolve the
42 conflict just like you would resolve a merge conflict in Git.
43 · The patch stack is just some extra metadata attached to regular Git
45 commits, so you can continue to use most Git tools along with
46 StGit.
47 Typical uses
49 Tracking branch
50 Tracking changes from a remote branch, while maintaining local
51 modifications against that branch, possibly with the intent of
52 sending some patches upstream. You can modify your patch stack as
53 much as you want, and when your patches are finally accepted
54 upstream, the permanent recorded Git history will contain just the
55 final sequence of patches, and not the messy sequence of edits that
56 produced them.
57 Commands of interest in this workflow are e.g. rebase and mail.
59 Development branch
61 Even if you have no "upstream" to send patches to, you can use
62 StGit as a convenient way to modify the recent history of a Git
63 branch. For example, instead of first committing change A, then
64 change B, and then A2 to fix A because it wasn’t quite right, you
65 could incorporate the fix directly into A. This way of working
66 results in a much more readable Git history than if you had
67 immortalized every misstep you made on your way to the right
68 solution.
69 Commands of interest in this workflow are e.g. uncommit, which can
71 be used to move the patch stack base downwards — i.e., turn Git
72 commits into StGit patches after the fact — and commit, its
73 inverse.
74 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
107 Prints the StGit version, as well as version of other components
108 used, such as Git and Python.
109 --help
111 Prints the synopsis and a list of all subcommands. If an StGit
112 subcommand is given, prints the synposis for that subcommand.
113
115 We divide StGit commands in thematic groups, according to the primary
116 type of object they create or change.
117 Here is a short description of each command. A more detailed
119 description is available in individual command manpages. Those manpages
120 are named stg-<command>(1).
121 Repository commands
123 stg-clone(1)
124 Make a local clone of a remote repository
125 stg-id(1)
127 Print the git hash value of a StGit reference
128 Stack (branch) commands
130 stg-branch(1)
131 Branch operations: switch, list, create, rename, delete, ...
132 stg-clean(1)
134 Delete the empty patches in the series
135 stg-commit(1)
137 Permanently store the applied patches into the stack base
138 stg-float(1)
140 Push patches to the top, even if applied
141 stg-goto(1)
143 Push or pop patches to the given one
144 stg-hide(1)
146 Hide a patch in the series
147 stg-init(1)
149 Initialise the current branch for use with StGIT
150 stg-log(1)
152 Display or optionally clear the patch changelog
153 stg-next(1)
155 Print the name of the next patch
156 stg-patches(1)
158 Show the applied patches modifying a file
159 stg-pop(1)
161 Pop one or more patches from the stack
162 stg-prev(1)
164 Print the name of the previous patch
165 stg-publish(1)
167 Push the stack changes to a merge-friendly branch
168 stg-pull(1)
170 Pull changes from a remote repository
171 stg-push(1)
173 Push one or more patches onto the stack
174 stg-rebase(1)
176 Move the stack base to another point in history
177 stg-redo(1)
179 Undo the last undo operation
180 stg-repair(1)
182 Fix StGit metadata if branch was modified with git commands
183 stg-reset(1)
185 Reset the patch stack to an earlier state
186 stg-series(1)
188 Print the patch series
189 stg-sink(1)
191 Send patches deeper down the stack
192 stg-squash(1)
194 Squash two or more patches into one
195 stg-top(1)
197 Print the name of the top patch
198 stg-uncommit(1)
200 Turn regular git commits into StGit patches
201 stg-undo(1)
203 Undo the last operation
204 stg-unhide(1)
206 Unhide a hidden patch
207 Patch commands
209 stg-delete(1)
210 Delete patches
211 stg-edit(1)
213 Edit a patch description or diff
214 stg-export(1)
216 Export patches to a directory
217 stg-files(1)
219 Show the files modified by a patch (or the current patch)
220 stg-fold(1)
222 Integrate a GNU diff patch into the current patch
223 stg-import(1)
225 Import a GNU diff file as a new patch
226 stg-mail(1)
228 Send a patch or series of patches by e-mail
229 stg-new(1)
231 Create a new, empty patch
232 stg-pick(1)
234 Import a patch from a different branch or a commit object
235 stg-refresh(1)
237 Generate a new commit for the current patch
238 stg-rename(1)
240 Rename a patch
241 stg-show(1)
243 Show the commit corresponding to a patch
244 stg-sync(1)
246 Synchronise patches with a branch or a series
247 Index/worktree commands
249 stg-diff(1)
250 Show the tree diff
251
253 StGit uses the same configuration mechanism as Git. See git(7) for more
254 details.
255
257 A number of StGit commands make use of template files to provide useful
258 default texts to be edited by the user. These <name>.tmpl template
259 files are searched in the following directories:
260 1. $GITDIR/ (in practice, the .git/ directory in your repository)
263 2. $HOME/.stgit/templates/
265 3. /usr/share/stgit/templates/
267
269 1. the tutorial
270 [set $man.base.url.for.relative.links]/tutorial.html
271StGit 01/31/2020 STG(1)