1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
stg(1)
======
Yann Dirson <ydirson@altern.org>
NAME
----
stg - Manage stacks of patches using the Git content tracker
SYNOPSIS
--------
[verse]
'stg' [--version | --help]
'stg' [--help <command> | <command> --help]
'stg' <command> [COMMAND OPTIONS] [ARGS]
DESCRIPTION
-----------
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.
Typical uses
~~~~~~~~~~~~
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. linkstgsub:rebase[] and
linkstgsub: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. linkstgsub:uncommit[],
which can be used to move the patch stack base downwards -- i.e., turn
Git commits into StGit patches after the fact -- and
linkstgsub:commit[], its inverse.
For more information, see link:tutorial.html[the tutorial].
Specifying patches
~~~~~~~~~~~~~~~~~~
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+).
Specifying commits
~~~~~~~~~~~~~~~~~~
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,
linkstg:id[] will convert it to a Git commit id for you.
OPTIONS
-------
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.
STGIT COMMANDS
--------------
We divide StGit commands in thematic groups, according to the primary
type of object they create or change.
ifdef::backend-docbook[]
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)'.
endif::backend-docbook[]
include::command-list.txt[]
CONFIGURATION MECHANISM
-----------------------
StGit uses the same configuration mechanism as Git. See linkman:git[7]
for more details.
TEMPLATES
---------
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:
. +$GITDIR/+ (in practice, the +.git/+ directory in your repository)
. +$HOME/.stgit/templates/+
. +/usr/share/stgit/templates/+
|
