stg(1)

NAME

stg - manage stacks of patches using the GIT content tracker

SYNOPSIS

stg [--version | --help]
stg [--help <command> | <command> --help]
stg <command> [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.

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.

Typical uses of StGIT include:

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.

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.

Development branch

Preparing and testing your commits before publishing them,
separating your features from unrelated bugfixes collected while
developping.

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.

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 stack are just referred to by their name. Some
commands allow you to specify a patch in another stack of the
repository; this is done by suffixing the patch name with an @ sign
followed by the branch name (eg. thispatch@otherbranch).

A number of positions in the stack related to the patch are also
accessible through // suffixes. For example, patch//top is equivalent to patch, and patch//bottom refers to the commit below patch (i.e. the patch below, or the stack base if this is the bottom-most patch).
Similarly //top.old and //bottom.old refer to the previous version of the patch (before the last stgpush or stgrefresh operation). When referring to the current patch, its name can be omitted (eg.
currentpatch//bottom.old can be abbreviated as bottom.old).

If you need to pass a given StGIT reference to a git command, stgid will convert it to a git commit id.

OPTIONS

The following generic option flags are available. Additional options
are available per-command, and documented in the command-specific
documentation.

--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.

--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.

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 stg-<command>(1).

Generic commands

User-support commands not touching the repository.

stg help

print the detailed command usage

stg version

display version information

stg copyright

display copyright information

Repository commands

stgclone

make a local clone of a remote repository

stgid

print the GIT hash value of a StGIT reference

Stack commands

Stack management

stgbranch

manage patch stacks

stginit

initialise the current branch for use with StGIT

stgclean

delete the empty patches in the series

stgpull

pull the changes from the remote repository

stgrebase

move the stack base to another point in history

stgcommit

permanently store the applied patches into stack base

stguncommit

turn regular GIT commits into StGIT patches

stgrepair

Fix StGit metadata if branch was modified with git commands

Controlling what patches are applied

stgseries

print the patch series

stgpush

push patches to the top, even if applied push or pop patches to the given one push one or more patches onto of the stack

stgpop

pop one or more patches from the stack

stggoto

push or pop patches to the given one

stgfloat

push patches to the top, even if applied

stgsink

send patches deeper down the stack

stgapplied

print the applied patches

stgunapplied

print the unapplied patches

stgtop

print the name of the top patch

stghide

hide a patch in the series

stgunhide

unhide a hidden patch in the series

Miscellaneous stack commands

stgpatches

show the applied patches modifying a file

Patch commands

Patch management

stgnew

create a new patch and make it the topmost one

stgdelete

delete the empty patches in the series delete patches

stgrename

rename a patch in the series

stglog

display the patch changelog

Controlling patch contents

stgfiles

show the files modified by a patch (or the current patch)

stgshow

show the applied patches modifying a file show the files
modified by a patch (or the current patch) show the commit
corresponding to a patch (or the current patch) show the
tree diff show the tree status

stgrefresh

generate a new commit for the current patch

stgfold

integrate a GNU diff patch into the current patch

stgpick

import a patch from a different branch or a commit object

stgsync

synchronise patches with a branch or a series

Interaction with the rest of the world

stgexport

exports patches to a directory

stgimport

import a GNU diff file as a new patch import a patch from a different branch or a commit object

stgmail

send a patch or series of patches by e-mail

Working-copy commands

stgadd

add files or directories to the repository

stgrm

remove files from the repository

stgcp

copy files inside the repository

stgstatus

show the tree status

stgdiff

show the tree diff

stgresolved

mark a file conflict as solved

CONFIGURATION MECHANISM

Starting with 0.12, StGIT uses the same configuration mechanism as GIT. See git7[1] 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/
$HOME/.stgit/templates/
/usr/share/stgit/templates/

NOTES

1. 7

git

04/04/2008 STG(1)