1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html><head><title>StGIT Wiki: StGIT Tutorial</title><link type="text/css" rel="stylesheet" href="/cgi-bin/wiki.cgi/StyleSheetPage?raw=3" /><meta name="robots" content="INDEX,NOFOLLOW" /><link rel="alternate" type="application/rss+xml" title="StGIT Wiki" href="/cgi-bin/wiki.cgi?action=rss" /><link rel="alternate" type="application/rss+xml" title="StGIT Wiki: StGIT_Tutorial" href="/cgi-bin/wiki.cgi?action=rss;rcidonly=StGIT_Tutorial" /></head><body class="/cgi-bin/wiki.cgi"><div class="header"><span class="gotobar bar"><a class="local" href="/cgi-bin/wiki.cgi/HomePage">HomePage</a> <a class="local" href="/cgi-bin/wiki.cgi/RecentChanges">RecentChanges</a> </span><h1><a title="Click to search for references to this page" href="/cgi-bin/wiki.cgi?search=StGIT+Tutorial">StGIT Tutorial</a></h1></div><div class="sidebar"></div><div class="content browse"><h2>Introduction</h2><p><a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> is a Python application that provides functionality similar to <a class="url outside" href="http://savannah.nongnu.org/projects/quilt/">quilt</a> (i.e. pushing/popping patches to/from a stack) using <a class="url outside" href="http://www.kernel.org/git/">GIT</a> instead of 'diff' and 'patch'. <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> stores its patches in a GIT repository as normal GIT commit objects.</p><p><a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> is not an SCM interface on top of GIT. For standard SCM operations use GIT's porcelain commands.</p><p><a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> is available for download at <a class="url" href="http://www.procode.org/stgit/">http://www.procode.org/stgit/</a> .</p><p><em>This tutorial assumes you are already familiar with GIT. For more information on GIT, see the <a class="url outside" href="http://www.kernel.org/git/?p=git/git.git;a=blob;f=Documentation/tutorial.txt">GIT tutorial</a> or <a class="url outside" href="http://www.kernel.org/pub/software/scm/git/docs/">git(7)</a> .</em></p><h2>Basic Operation</h2><h3>Help</h3><p>For a full list of <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> commands:</p><pre class="real">stg --help
</pre><p>For help on individual subcommands:</p><pre class="real">stg <cmd> (-h | --help)
</pre><h3>Repository initialisation</h3><p>In stand-alone mode, <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> is used in conjunction with a GIT repository that is already initialised (using 'git-init-db'). <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> cannot be used outside of a GIT repository.</p><p>Any branch in a GIT repository may be managed by <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>. Each branch managed by <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> contains an independent series of <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patches.</p><p>To initialise an existing GIT branch to be managed by <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>, cd into the top of your GIT repository, check out the branch you'd like to manage with <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>, and type:</p><pre class="real">stg init
</pre><p>Run the 'stg init' command for any pre-existing GIT branches intended to be used with <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>.</p><p>As a convention, you should avoid working in the 'master' branch of a remote project and use it only as a reference, since it reflects someone else's work.</p><p>You can switch between GIT branches with:</p><pre class="real">stg branch [<branch name>]
</pre><p>This checks out the named branch and places you at the topmost applied <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patch in that branch.</p><p>Alternately, you can create branches using only <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> commands, which will automatically prepare them for use with <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>:</p><pre class="real">stg branch --create <new branch>
</pre><h3>Working with remote repositories</h3><p>With a single command, <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> can create and initialize a GIT repository which mirrors a remote GIT repository. This is known as <em>cloning</em>. All GIT transports are supported.</p><p>To clone a repository, use:</p><pre class="real">stg clone <repository> <local-dir>
</pre><p>This creates a fresh local repository, initialises a GIT database in it, pulls the latest version of the remote, and creates and initialises a 'master' branch for use with <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>.</p><p>At any time you can pull the latest changes from the remote repository. By default, <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> pulls from the location stored in .git/branches/origin, and updates the base of the current branch.</p><p>To pull the latest changes from a remote repository, use:</p><pre class="real">stg pull [<branch> or 'origin']
</pre><p>This command removes all applied <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patches from the current branch, updates the branch's base commit, then attempts to re-apply the patches. Any merge conflicts will halt this process, allowing you to clean up the conflicts and continue (see below).</p><p>If the maintainer of the remote repository includes one of your patches in the published repository that you pull from, <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> can usually recognize that an incoming patch from the remote matches one of yours, and it turns your local version into an empty patch.</p><p>To automatically delete empty patches after a pull, use:</p><pre class="real">stg clean
</pre><p>As a convention, you should avoid working in the 'master' branch and use it only as a reference, since it reflects someone else's work. If you decide to publish your GIT repository, you'll want your own work separated into its own branch to make it convenient for others to pull just your patches.</p><h3>Getting started: creating a patch</h3><p>Changes to your working directory are saved in a <em>patch.</em> An <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patch is simply a saved set of modifications to your working directory, plus a saved description. To create an empty <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patch in the current branch:</p><pre class="real">stg new <name>
</pre><p>To save the changes you've made (that is, to <em>refresh</em> a patch), use:</p><pre class="real">stg refresh
</pre><p>To discard changes in your working directory, use:</p><pre class="real">git checkout -f
</pre><p>This restores your working directory to the state it was in the last time the patch was refreshed.</p><p>Modified files that haven't been saved via a refresh operation can be viewed with:</p><pre class="real">stg status
</pre><p>You can view modified files that have already been saved into a patch:</p><pre class="real">stg files
</pre><p>The 'stg refresh' command automatically notes changes to files that already exist in the working directory, but you have to tell <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> explicitly if you add, remove, or rename files.</p><p>To record the addition or deletion of files in your new patch:</p><pre class="real">stg add [<file>*]
stg rm [<file>*]
</pre><p>To record the renaming of a file in your new patch, issue both of these commands:</p><pre class="real">stg rm <oldfilename>
stg add <newfilename>
</pre><h3>Stack manipulation: managing multiple patches</h3><p><a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> can manage more than one patch at a time. A series of <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patches in a GIT branch are known collectively as a <em>stack.</em> The new patch you created above is now the topmost patch in your stack. You can always see the name of the topmost (current) patch with:</p><pre class="real">stg top
</pre><p>The topmost patch is used as the default patch for most <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> operations. It is the default target of the 'stg refresh' command, for example.</p><p>Patches that are pushed onto the stack are referred to as <em>applied</em>, and patches that are popped off the stack are referred to as <em>unapplied</em>.</p><p>To push/pop a patch to/from a stack:</p><pre class="real">stg push [--all | <name>]
stg pop [--all]
</pre><p>The last patch you pushed is the topmost patch. This patch is always in the applied list; <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> can't operate on an unapplied patch unless you apply it first.</p><p>You can display the order of patches in a stack with one of these commands:</p><pre class="real">stg series
stg applied
stg unapplied
</pre><p>By default the 'stg push' command applies the first patch in the <em>unapplied</em> list, but you can push any patch in the unapplied list by giving the name of the patch. This is useful if you want to reorder the patches in a stack.</p><p>During a push operation, merge conflicts can occur (especially if you are changing the order of the patches in your stack). If the push causes merge conflicts, they need to be fixed and 'stg resolved' run (see below). A 'push' operation can also be reverted with 'stg push --undo'.</p><p>A few more stack basics; to rename a patch:</p><pre class="real">stg rename <old-name> <new-name>
</pre><p>To delete a patch:</p><pre class="real">stg delete <name>
</pre><p>This permanently discards the named patch. In other words, the patch no longer appears in either the applied or unapplied lists, and cannot be reapplied to the series.</p><p>You may want to make patches in your stack a permanent part of your GIT repository, for example if you are publishing your repository to others. To do this, use:</p><pre class="real">stg commit
</pre><p>This merges all <em>applied</em> patches in your patch series into the GIT repository and removes them from your stack. Use this command only if you want to permanently store the applied patches and no longer manage them with <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>.</p><h3>Converting between StGIT patches and text diffs</h3><p>As mentioned in the introduction, <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> stores modifications to your working tree in the form of GIT commits. This means if you want to apply your changes to a tree not managed by GIT, or send your changes to someone else in e-mail, you need to convert your <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patches into normal textual diffs that can be applied with the GNU 'patch' command.</p><p>The 'stg diff' command is a powerful way to generate and view textual diffs of patches managed by <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a>.</p><p>To view a diff of the topmost patch:</p><pre class="real">stg diff -r /
</pre><p>Observe that this does not show any changes in the working directory that have not been saved by a 'refresh'. To view just the changes you've made since the last refresh, use:</p><pre class="real">stg diff -r /top
</pre><p>If you want to see the changes made by the patch combined with any unsaved changes in the working directory, try:</p><pre class="real">stg diff -r /bottom
</pre><p>You can also show the changes to any patch in your stack with:</p><pre class="real">stg diff -r <patch>/
</pre><p>Use this command to view all the changes in your stack up through the current patch:</p><pre class="real">stg diff -r base
</pre><p>The 'stg diff' command supports a number of other features that are very useful. Be sure to take a look at the help information for this command.</p><p>To convert your <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patches into patch files:</p><pre class="real">stg export [--range=[<patch1>[:<patch2>]]] [<dir-name>]
</pre><p>The 'export' command supports options to automatically number the patches (-n) or add the '.diff' extension (-d). If you don't tell "stg export" where to put the patches, it will create directory named "patch-branchname" in your current directory, and store the patches there.</p><p>To e-mail a patch or range of patches:</p><pre class="real">stg mail [--to=...] (--all | --range=[<patch1>[:<patch2>]] | <patch>)
</pre><p>"stg mail" has a lot of options, so read the output of "stg mail -h" for more information.</p><p>You can also import an existing GNU diff patch file as a new <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patch with a single command. "stg import" will automatically parse through the patch file and extract a patch description. Use:</p><pre class="real">stg import [<file>]
</pre><p>This is the equivalent of "stg new" followed by "patch -i <file>", then "stg refresh -e".</p><p>Sometimes the patch file won't apply cleanly. In that case, "stg import" will leave you with an empty <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patch, to which you then apply the patch file by hand using "patch -i" and your favorite editor.</p><p>To merge a GNU diff file (defaulting to the standard input) into the topmost patch:</p><pre class="real">stg fold [<file>]
</pre><p>This command supports a '--threeway' option which applies the patch onto the bottom of the topmost one and performs a three-way merge.</p><h2>Advanced Usage</h2><h3>Handling merge conflicts</h3><p>Pushing a patch on the stack can fail if the patch cannot be applied cleanly. This usually happens if there are overlapping changes in the tree, the patch depends on another patch which is not applied, or if a patch was not merged upstream in the exact form it was sent.</p><p>The 'push' operation stops after the first patch with conflicts. The 'status' command shows the conflict files by marking them with a 'C'. If the 'keeporig' options is set to 'yes' (the default), the original files involved in the merge operations are left in the tree as <file>.older, <file>.local and <file>.remote for better analysis of the conflict. If 'diff3' is used as the merger (the default), markers are added to the conflicted files as well.</p><p>Run the 'resolved' command to mark the conflicts resolved and remove the temporary merge files from the working tree. Then run the 'refresh' command to update the <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> patch with the modifications you made to resolve the conflict.</p><h3>Configuration file</h3><p><a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> tries to read the configuration options from the following files: /etc/stgitrc, ~/.stgitrc and .git/stgitrc. The latter overrides the options in the former files. If no file is found, the defaults are used.</p><p>An example configuration file with options description can be found in the examples/ directory. Most users would probably only define the 'smtpserver' option used by the 'mail' command.</p><p>The gitmergeonefile.py script does the three-way merging on individual files using the tool specified by the 'merger' option. The user can specify a smarter tool to be used.</p><h3>Templates</h3><p>The 'export' and 'mail' commands use templates for generating the patch files or e-mails. The default templates are installed under <prefix>/share/stgit/templates/ and, combined with the extra options available for the commands, should be enough for most users. The template format uses the standard Python string formatting rules. The variables available are shown in the the help message for the commands.</p><p>The 'mail' command can also send an initial e-mail for which there is no default template. The <prefix>/share/stgit/examples/covermail.tmpl file can be used as an example.</p><p>A default description for new patches can be defined in the .git/patchdescr.tmpl file. This is useful for things like signed-off-by lines.</p><h3>Merging two patches into one</h3><p>There used to be no command to do this directly at the moment but one can export the patch to be merged and use the 'stg fold' command on the generated diff file. Since 0.8, "stg pick --fold <patch>" will merge <patch> into the current one. Assuming that the merged patch was not already applied, the operation will succeed. Pushing the merged patch onto the stack will result in an empty patch (<a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> notifying the user) that can be safely deleted.</p><h3>The Theory behind StGIT</h3><p>More information about how <a class="local" href="/cgi-bin/wiki.cgi/StGIT">StGIT</a> works can be found <a class="local" href="/cgi-bin/wiki.cgi/StGITtheory">here</a>.</p></div><div class="footer"><hr /><span class="gotobar bar"><a class="local" href="/cgi-bin/wiki.cgi/HomePage">HomePage</a> <a class="local" href="/cgi-bin/wiki.cgi/RecentChanges">RecentChanges</a> </span><span class="edit bar"><br /> <a class="local" href="/cgi-bin/wiki.cgi/Comments_On_StGIT_Tutorial">Comments On StGIT Tutorial</a> <a href="/cgi-bin/wiki.cgi?action=password">This page is read-only</a> <a class="history" href="/cgi-bin/wiki.cgi?action=history;id=StGIT_Tutorial">View revisions</a> <a class="admin" href="/cgi-bin/wiki.cgi?action=admin;id=StGIT_Tutorial">Administration</a> <a href="http://www.memebot.com">Memebot</a> <a href="http://www.oddmuse.org">Oddmuse</a></span><span class="time"><br /> Last edited 2006-12-26 15:03 UTC by <a class="author" title="from 12-216-24-118.client.mchsi.com" href="/cgi-bin/wiki.cgi/KenMacLeod">KenMacLeod</a> <a class="diff" href="/cgi-bin/wiki.cgi?action=browse;diff=2;id=StGIT_Tutorial">(diff)</a></span><form method="get" action="/cgi-bin/wiki.cgi" enctype="multipart/form-data" class="search">
<p>Search: <input type="text" name="search" size="20" accesskey="f" /> <input type="submit" name="dosearch" value="Go!" /></p></form></div>
</body>
</html>
|
