| 1 | stg(1) |
| 2 | ====== |
| 3 | Yann Dirson <ydirson@altern.org> |
| 4 | |
| 5 | NAME |
| 6 | ---- |
| 7 | stg - Manage stacks of patches using the Git content tracker |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'stg' [--version | --help] |
| 13 | 'stg' [--help <command> | <command> --help] |
| 14 | 'stg' <command> [COMMAND OPTIONS] [ARGS] |
| 15 | |
| 16 | DESCRIPTION |
| 17 | ----------- |
| 18 | |
| 19 | StGit (Stacked Git) is an application that provides a convenient way |
| 20 | to maintain a 'patch stack' on top of a Git branch: |
| 21 | |
| 22 | * The topmost (most recent) commits of a branch are given names. |
| 23 | Such a named commit is called a 'patch'. |
| 24 | |
| 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 | |
| 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 | |
| 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 | ~~~~~~~~~~~~ |
| 55 | |
| 56 | Tracking branch:: |
| 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. |
| 65 | + |
| 66 | Commands of interest in this workflow are e.g. linkstgsub:rebase[] and |
| 67 | linkstgsub:mail[]. |
| 68 | |
| 69 | Development branch:: |
| 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. |
| 79 | + |
| 80 | Commands of interest in this workflow are e.g. linkstgsub: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 | linkstgsub:commit[], its inverse. |
| 84 | |
| 85 | For more information, see htmllink:tutorial.html[the tutorial]. |
| 86 | |
| 87 | Specifying patches |
| 88 | ~~~~~~~~~~~~~~~~~~ |
| 89 | |
| 90 | Many StGit commands take references to StGit patches as arguments. |
| 91 | Patches in the stack are identified with short names, each of which |
| 92 | must be unique in the stack. |
| 93 | |
| 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+. |
| 108 | |
| 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+. |
| 112 | |
| 113 | If you need to pass a given StGit reference to a Git command, |
| 114 | linkstg:id[] will convert it to a Git commit id for you. |
| 115 | |
| 116 | OPTIONS |
| 117 | ------- |
| 118 | |
| 119 | The following generic option flags are available. Additional options |
| 120 | are available for (and documented with) the different subcommands. |
| 121 | |
| 122 | --version:: |
| 123 | Prints the StGit version, as well as version of other components |
| 124 | used, such as Git and Python. |
| 125 | |
| 126 | --help:: |
| 127 | Prints the synopsis and a list of all subcommands. If an StGit |
| 128 | subcommand is given, prints the synposis for that subcommand. |
| 129 | |
| 130 | STGIT COMMANDS |
| 131 | -------------- |
| 132 | |
| 133 | We divide StGit commands in thematic groups, according to the primary |
| 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 | |
| 142 | include::command-list.txt[] |
| 143 | |
| 144 | CONFIGURATION MECHANISM |
| 145 | ----------------------- |
| 146 | |
| 147 | StGit uses the same configuration mechanism as Git. See manlink:git[7] |
| 148 | for more details. |
| 149 | |
| 150 | TEMPLATES |
| 151 | --------- |
| 152 | |
| 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+ |
| 155 | template files are searched in the following directories: |
| 156 | |
| 157 | . +$GITDIR/+ (in practice, the +.git/+ directory in your repository) |
| 158 | . +$HOME/.stgit/templates/+ |
| 159 | . +/usr/share/stgit/templates/+ |