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

CONFIGURATION MECHANISM

123       StGit uses the same configuration mechanism as Git. See git(7) for more
124       details.
125

TEMPLATES

127       A number of StGit commands make use of template files to provide useful
128       default texts to be edited by the user. These <name>.tmpl template
129       files are searched in the following directories:
130
131
132        1. $GITDIR/ (in practice, the .git/ directory in your repository)
133
134        2. $HOME/.stgit/templates/
135
136        3. /usr/share/stgit/templates/
137

NOTES

139        1. the tutorial
140           [set $man.base.url.for.relative.links]/tutorial.html
141
142
143
144StGit                             07/27/2019                            STG(1)
Impressum