X-Git-Url: https://git.distorted.org.uk/~mdw/stgit/blobdiff_plain/bfbfd4e58d129d083fadb083a8ffb7982086a3ec..03fc3b26aee0b216513b2077c6b009f896458ca1:/Documentation/stg.txt diff --git a/Documentation/stg.txt b/Documentation/stg.txt index 7d92356..4cdff53 100644 --- a/Documentation/stg.txt +++ b/Documentation/stg.txt @@ -1,71 +1,136 @@ -stg(7) +stg(1) ====== Yann Dirson -v0.12.1, February 2007 NAME ---- -stg - manage stacks of patches using the GIT content tracker +stg - Manage stacks of patches using the Git content tracker SYNOPSIS -------- [verse] -'stg' [--version] [--help] [OPTIONS] [ARGS] +'stg' [--version | --help] +'stg' [--help | --help] +'stg' [COMMAND OPTIONS] [ARGS] DESCRIPTION ----------- -StGIT (Stacked GIT) is an application providing similar functionality -to Quilt (i.e. pushing/popping patches to/from a stack), on top of -GIT. These operations are performed using GIT commands and the patches -are stored as GIT commit objects, allowing easy merging of the StGIT -patches into other repositories using standard GIT functionality. +StGit (Stacked Git) is an application that provides a convenient way +to maintain a 'patch stack' on top of a Git branch: -An StGIT stack is a GIT branch with additional information to help -making changes to individual patches you already committed, rather -than making changes by adding new commits. It is thus a -non-forwarding, or rewinding branch: the old head of the branch is -often not reachable as one of the new head's ancestors. + * The topmost (most recent) commits of a branch are given names. + Such a named commit is called a 'patch'. -Typical uses of StGIT include: + * 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. StGIT assists in preparing and - cleaning up patches until they are acceptable upstream, as - well as maintaining local patches not meant to be sent - upstream. + + 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. + -In such a setup, typically all commits on your branch are StGIT -patches; the stack base is the branch point where your changes "fork" -off their parent branch. +Commands of interest in this workflow are e.g. linkstgsub:rebase[] and +linkstgsub:mail[]. Development branch:: - Preparing and testing your commits before publishing them, - separating your features from unrelated bugfixes collected - while developping. + + 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. + -In such a setup, not all commits on your branch need to be StGIT -patches; there may be regular GIT commits below your stack base. +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 htmllink: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 suite version that the 'stg' program came - from, as well as version of other components used, such as GIT - and Python. + 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 commands. If a git - command is given this option will display the specific help - for that command. + 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 +We divide StGit commands in thematic groups, according to the primary type of object they create or change. ifdef::backend-docbook[] @@ -74,153 +139,21 @@ description is available in individual command manpages. Those manpages are named 'stg-(1)'. endif::backend-docbook[] -Generic commands -~~~~~~~~~~~~~~~~ - -User-support commands not touching the repository. - -stg help:: - stgdesc:help[] -stg version:: - stgdesc:version[] -stg copyright:: - stgdesc:copyright[] - -Repository commands -~~~~~~~~~~~~~~~~~~~ - -stglink:clone[]:: - stgdesc:clone[] -stglink:id[]:: - stgdesc:id[] - -Stack commands -~~~~~~~~~~~~~~ - -Stack management -^^^^^^^^^^^^^^^^ - -stglink:branch[]:: - stgdesc:branch[] -stglink:init[]:: - stgdesc:init[] -stglink:clean[]:: - stgdesc:clean[] -stglink:pull[]:: - stgdesc:pull[] -stglink:rebase[]:: - stgdesc:rebase[] - -stglink:commit[]:: - stgdesc:commit[] -stglink:uncommit[]:: - stgdesc:uncommit[] -stglink:assimilate[]:: - stgdesc:assimilate[] - -Controlling what patches are applied -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -stglink:series[]:: - stgdesc:series[] -stglink:push[]:: - stgdesc:push[] -stglink:pop[]:: - stgdesc:pop[] -stglink:goto[]:: - stgdesc:goto[] -stglink:float[]:: - stgdesc:float[] -stglink:applied[]:: - stgdesc:applied[] -stglink:unapplied[]:: - stgdesc:unapplied[] -stglink:top[]:: - stgdesc:top[] - -stglink:hide[]:: - stgdesc:hide[] -stglink:unhide[]:: - stgdesc:unhide[] - -Miscellaneous stack commands -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -stglink:patches[]:: - stgdesc:patches[] - - -Patch commands -~~~~~~~~~~~~~~ - -Patch management -^^^^^^^^^^^^^^^^ - -stglink:new[]:: - stgdesc:new[] -stglink:delete[]:: - stgdesc:delete[] -stglink:rename[]:: - stgdesc:rename[] -stglink:log[]:: - stgdesc:log[] - -Controlling patch contents -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -stglink:files[]:: - stgdesc:files[] -stglink:show[]:: - stgdesc:show[] -stglink:refresh[]:: - stgdesc:refresh[] -stglink:fold[]:: - stgdesc:fold[] -stglink:pick[]:: - stgdesc:pick[] -stglink:sync[]:: - stgdesc:sync[] - -Interaction with the rest of the world -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -stglink:export[]:: - stgdesc:export[] -stglink:import[]:: - stgdesc:import[] -stglink:mail[]:: - stgdesc:mail[] - - -Working-copy commands -~~~~~~~~~~~~~~~~~~~~~ - -stglink:add[]:: - stgdesc:add[] -stglink:rm[]:: - stgdesc:rm[] -stglink:cp[]:: - stgdesc:cp[] -stglink:status[]:: - stgdesc:status[] -stglink:diff[]:: - stgdesc:diff[] -stglink:resolved[]:: - stgdesc:resolved[] +include::command-list.txt[] CONFIGURATION MECHANISM ----------------------- -Starting with 0.12, StGIT uses the same configuration mechanism as -GIT. See gitlink:git[7] for more details. +StGit uses the same configuration mechanism as Git. See manlink: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 '.tmpl' +A number of StGit commands make use of template files to provide +useful default texts to be edited by the user. These +.tmpl+ template files are searched in the following directories: - $GITDIR/ - $HOME/.stgit/templates/ - /usr/share/stgit/templates/ + . +$GITDIR/+ (in practice, the +.git/+ directory in your repository) + . +$HOME/.stgit/templates/+ + . +/usr/share/stgit/templates/+