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