| 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/+ |