'\" t
.\"     Title: stg
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/02/2017
.\"    Manual: StGit Manual
.\"    Source: StGit
.\"  Language: English
.\"
.TH "STG" "1" "09/02/2017" "StGit" "StGit Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
stg \- Manage stacks of patches using the Git content tracker
.SH "SYNOPSIS"
.sp
.nf
\fIstg\fR [\-\-version | \-\-help]
\fIstg\fR [\-\-help <command> | <command> \-\-help]
\fIstg\fR <command> [COMMAND OPTIONS] [ARGS]
.fi
.SH "DESCRIPTION"
StGit (Stacked Git) is an application that provides a convenient way to maintain a \fIpatch stack\fR on top of a Git branch:

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The topmost (most recent) commits of a branch are given names\&. Such a named commit is called a \fIpatch\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
After making changes to the worktree, you can incorporate the changes into an existing patch; this is called \fIrefreshing\fR\&. You may refresh any patch, not just the topmost one\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
You can \fIpop\fR a patch: temporarily putting it aside, so that the patch below it becomes the topmost patch\&. Later you may \fIpush\fR it onto the stack again\&. Pushing and popping can be used to reorder patches\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
You can easily \fIrebase\fR your patch stack on top of any other Git commit\&. (The \fIbase\fR 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\(cqs branch, and that person publishes an updated branch, you can take all your patches and apply them on top of the updated branch\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
As you would expect, changing what is below a patch can cause that patch to no longer apply cleanly \(em this can occur when you reorder patches, rebase patches, or refresh a non\-topmost patch\&. StGit uses Git\(cqs 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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.SS "Typical uses"
.PP
Tracking branch
.RS 4
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\&. rebase and mail\&.
.RE
.PP
Development branch
.RS 4
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 \fIA\fR, then change \fIB\fR, and then \fIA2\fR to fix \fIA\fR because it wasn\(cqt quite right, you could incorporate the fix directly into \fIA\fR\&. 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\&. uncommit, which can be used to move the patch stack base downwards \(em i\&.e\&., turn Git commits into StGit patches after the fact \(em and commit, its inverse\&.
.RE
For more information, see \m[blue]\fBthe tutorial\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SS "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)\&.
.SS "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, \fBstg-id\fR(1) will convert it to a Git commit id for you\&.
.SH "OPTIONS"
The following generic option flags are available\&. Additional options are available for (and documented with) the different subcommands\&.

.PP
\-\-version
.RS 4
Prints the StGit version, as well as version of other components used, such as Git and Python\&.
.RE
.PP
\-\-help
.RS 4
Prints the synopsis and a list of all subcommands\&. If an StGit subcommand is given, prints the synposis for that subcommand\&.
.RE
.SH "STGIT COMMANDS"
We divide StGit commands in thematic groups, according to the primary type of object they create or change\&.

Here is a short description of each command\&. A more detailed description is available in individual command manpages\&. Those manpages are named \fIstg\-<command>(1)\fR\&.
.SS "Repository commands"
.PP
\fBstg-clone\fR(1)
.RS 4
Make a local clone of a remote repository
.RE
.PP
\fBstg-id\fR(1)
.RS 4
Print the git hash value of a StGit reference
.RE
.SS "Stack (branch) commands"
.PP
\fBstg-branch\fR(1)
.RS 4
Branch operations: switch, list, create, rename, delete, \&...
.RE
.PP
\fBstg-clean\fR(1)
.RS 4
Delete the empty patches in the series
.RE
.PP
\fBstg-commit\fR(1)
.RS 4
Permanently store the applied patches into the stack base
.RE
.PP
\fBstg-float\fR(1)
.RS 4
Push patches to the top, even if applied
.RE
.PP
\fBstg-goto\fR(1)
.RS 4
Push or pop patches to the given one
.RE
.PP
\fBstg-hide\fR(1)
.RS 4
Hide a patch in the series
.RE
.PP
\fBstg-init\fR(1)
.RS 4
Initialise the current branch for use with StGIT
.RE
.PP
\fBstg-log\fR(1)
.RS 4
Display the patch changelog
.RE
.PP
\fBstg-next\fR(1)
.RS 4
Print the name of the next patch
.RE
.PP
\fBstg-patches\fR(1)
.RS 4
Show the applied patches modifying a file
.RE
.PP
\fBstg-pop\fR(1)
.RS 4
Pop one or more patches from the stack
.RE
.PP
\fBstg-prev\fR(1)
.RS 4
Print the name of the previous patch
.RE
.PP
\fBstg-publish\fR(1)
.RS 4
Push the stack changes to a merge\-friendly branch
.RE
.PP
\fBstg-pull\fR(1)
.RS 4
Pull changes from a remote repository
.RE
.PP
\fBstg-push\fR(1)
.RS 4
Push one or more patches onto the stack
.RE
.PP
\fBstg-rebase\fR(1)
.RS 4
Move the stack base to another point in history
.RE
.PP
\fBstg-redo\fR(1)
.RS 4
Undo the last undo operation
.RE
.PP
\fBstg-repair\fR(1)
.RS 4
Fix StGit metadata if branch was modified with git commands
.RE
.PP
\fBstg-reset\fR(1)
.RS 4
Reset the patch stack to an earlier state
.RE
.PP
\fBstg-series\fR(1)
.RS 4
Print the patch series
.RE
.PP
\fBstg-sink\fR(1)
.RS 4
Send patches deeper down the stack
.RE
.PP
\fBstg-squash\fR(1)
.RS 4
Squash two or more patches into one
.RE
.PP
\fBstg-top\fR(1)
.RS 4
Print the name of the top patch
.RE
.PP
\fBstg-uncommit\fR(1)
.RS 4
Turn regular git commits into StGit patches
.RE
.PP
\fBstg-undo\fR(1)
.RS 4
Undo the last operation
.RE
.PP
\fBstg-unhide\fR(1)
.RS 4
Unhide a hidden patch
.RE
.SS "Patch commands"
.PP
\fBstg-delete\fR(1)
.RS 4
Delete patches
.RE
.PP
\fBstg-edit\fR(1)
.RS 4
Edit a patch description or diff
.RE
.PP
\fBstg-export\fR(1)
.RS 4
Export patches to a directory
.RE
.PP
\fBstg-files\fR(1)
.RS 4
Show the files modified by a patch (or the current patch)
.RE
.PP
\fBstg-fold\fR(1)
.RS 4
Integrate a GNU diff patch into the current patch
.RE
.PP
\fBstg-import\fR(1)
.RS 4
Import a GNU diff file as a new patch
.RE
.PP
\fBstg-mail\fR(1)
.RS 4
Send a patch or series of patches by e\-mail
.RE
.PP
\fBstg-new\fR(1)
.RS 4
Create a new, empty patch
.RE
.PP
\fBstg-pick\fR(1)
.RS 4
Import a patch from a different branch or a commit object
.RE
.PP
\fBstg-refresh\fR(1)
.RS 4
Generate a new commit for the current patch
.RE
.PP
\fBstg-rename\fR(1)
.RS 4
Rename a patch
.RE
.PP
\fBstg-show\fR(1)
.RS 4
Show the commit corresponding to a patch
.RE
.PP
\fBstg-sync\fR(1)
.RS 4
Synchronise patches with a branch or a series
.RE
.SS "Index/worktree commands"
.PP
\fBstg-diff\fR(1)
.RS 4
Show the tree diff
.RE
.SH "CONFIGURATION MECHANISM"
StGit uses the same configuration mechanism as Git\&. See \fBgit\fR(7) for more details\&.
.SH "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:

.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
$GITDIR/ (in practice, the \&.git/ directory in your repository)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
$HOME/\&.stgit/templates/
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
/usr/share/stgit/templates/
.RE
.SH "NOTES"
.IP " 1." 4
the tutorial
.RS 4
\%[set $man.base.url.for.relative.links]/tutorial.html
.RE