1STG(1)                           StGit Manual                           STG(1)
2
3
4

NAME

6       stg - Manage stacks of patches using the Git content tracker
7

SYNOPSIS

9       stg [--version | --help]
10       stg [--help <command> | <command> --help]
11       stg <command> [COMMAND OPTIONS] [ARGS]
12

DESCRIPTION

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
17
18       ·   The topmost (most recent) commits of a branch are given names. Such
19           a named commit is called a patch.
20
21       ·   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
25       ·   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
30       ·   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
37       ·   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
44       ·   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
48   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
58           Commands of interest in this workflow are e.g. rebase and mail.
59
60       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
70           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
76   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
81       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
86   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
94       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
98       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

OPTIONS

102       The following generic option flags are available. Additional options
103       are available for (and documented with) the different subcommands.
104
105
106       --version
107           Prints the StGit version, as well as version of other components
108           used, such as Git and Python.
109
110       --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

STGIT COMMANDS

115       We divide StGit commands in thematic groups, according to the primary
116       type of object they create or change.
117
118       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
122   Repository commands
123       stg-clone(1)
124           Make a local clone of a remote repository
125
126       stg-id(1)
127           Print the git hash value of a StGit reference
128
129   Stack (branch) commands
130       stg-branch(1)
131           Branch operations: switch, list, create, rename, delete, ...
132
133       stg-clean(1)
134           Delete the empty patches in the series
135
136       stg-commit(1)
137           Permanently store the applied patches into the stack base
138
139       stg-float(1)
140           Push patches to the top, even if applied
141
142       stg-goto(1)
143           Push or pop patches to the given one
144
145       stg-hide(1)
146           Hide a patch in the series
147
148       stg-init(1)
149           Initialise the current branch for use with StGIT
150
151       stg-log(1)
152           Display or optionally clear the patch changelog
153
154       stg-next(1)
155           Print the name of the next patch
156
157       stg-patches(1)
158           Show the applied patches modifying a file
159
160       stg-pop(1)
161           Pop one or more patches from the stack
162
163       stg-prev(1)
164           Print the name of the previous patch
165
166       stg-publish(1)
167           Push the stack changes to a merge-friendly branch
168
169       stg-pull(1)
170           Pull changes from a remote repository
171
172       stg-push(1)
173           Push one or more patches onto the stack
174
175       stg-rebase(1)
176           Move the stack base to another point in history
177
178       stg-redo(1)
179           Undo the last undo operation
180
181       stg-repair(1)
182           Fix StGit metadata if branch was modified with git commands
183
184       stg-reset(1)
185           Reset the patch stack to an earlier state
186
187       stg-series(1)
188           Print the patch series
189
190       stg-sink(1)
191           Send patches deeper down the stack
192
193       stg-squash(1)
194           Squash two or more patches into one
195
196       stg-top(1)
197           Print the name of the top patch
198
199       stg-uncommit(1)
200           Turn regular git commits into StGit patches
201
202       stg-undo(1)
203           Undo the last operation
204
205       stg-unhide(1)
206           Unhide a hidden patch
207
208   Patch commands
209       stg-delete(1)
210           Delete patches
211
212       stg-edit(1)
213           Edit a patch description or diff
214
215       stg-export(1)
216           Export patches to a directory
217
218       stg-files(1)
219           Show the files modified by a patch (or the current patch)
220
221       stg-fold(1)
222           Integrate a GNU diff patch into the current patch
223
224       stg-import(1)
225           Import a GNU diff file as a new patch
226
227       stg-mail(1)
228           Send a patch or series of patches by e-mail
229
230       stg-new(1)
231           Create a new, empty patch
232
233       stg-pick(1)
234           Import a patch from a different branch or a commit object
235
236       stg-refresh(1)
237           Generate a new commit for the current patch
238
239       stg-rename(1)
240           Rename a patch
241
242       stg-show(1)
243           Show the commit corresponding to a patch
244
245       stg-sync(1)
246           Synchronise patches with a branch or a series
247
248   Index/worktree commands
249       stg-diff(1)
250           Show the tree diff
251

CONFIGURATION MECHANISM

253       StGit uses the same configuration mechanism as Git. See git(7) for more
254       details.
255

TEMPLATES

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
261
262        1. $GITDIR/ (in practice, the .git/ directory in your repository)
263
264        2. $HOME/.stgit/templates/
265
266        3. /usr/share/stgit/templates/
267

NOTES

269        1. the tutorial
270           [set $man.base.url.for.relative.links]/tutorial.html
271
272
273
274StGit                             01/31/2020                            STG(1)
Impressum