course/stgit.html

   1 <?xml version="1.0" encoding="iso-8859-1" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6         <title>Git - StGit Crash Course</title>
   7         <meta name="description" content="StGit crash course tutorial" />
   8         <meta name="author" content="Petr Baudis" />
   9         <meta http-equiv="reply-to" content="pasky@suse.cz" />
  10         <meta http-equiv="content-language" content="en" />
  11         <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  12         <link type="text/css" rel="stylesheet" media="screen" href="../stylesheets/screen.css" />
  13         <link type="text/css" title="Default" rel="stylesheet" media="screen" href="../stylesheets/screen-default.css" />
  14         <link type="text/css" title="Gitweb Gray" rel="alternate stylesheet" media="screen" href="../stylesheets/screen-gitweb-gray.css" />
  15         <link type="text/css" title="Blue" rel="alternate stylesheet" media="screen" href="../stylesheets/screen-blue.css" />
  16         <link type="text/css" title="Green" rel="alternate stylesheet" media="screen" href="../stylesheets/screen-green.css" />
  17         <link rel="icon" href="favicon.png" type="image/png" />
  18 </head>
  19
  20 <body>
  21
  22 <table border="1" summary="Navigation links" class="header" width="100%"><tr><td>
  23         <a href="../index.html" id="top"><img src="../git-logo.png" width="72" height="27" alt="Git"
  24                 style="border-width:0px;"/></a>
  25         <span class="hide">:</span>
  26         <span class="menu">
  27                 <a href="../index.html">Home</a> |
  28                 <a href="http://www.kernel.org/pub/software/scm/git/docs/">Documentation</a> |
  29                 <a href="http://git.or.cz/gitwiki">Wiki</a> |
  30                 <a href="http://www.kernel.org/pub/software/scm/git/">Download Site</a> |
  31                 <a href="http://www.kernel.org/git/?p=git/git.git;a=summary">Git's Gitweb</a>
  32         </span>
  33 </td></tr></table>
  34
  35 <h1>StGit Crash Course</h1>
  36
  37 <p>This tutorial should get you started with the StGit tool, which
  38 is intended for conveniently maintaining a patch series on top of
  39 a Git repository. You can reorder, push and pop patches, merge them
  40 together and mail them out individually or as a patch series.</p>
  41
  42 <p>It is assumed that you know basics of Git and Cogito at this
  43 point, but you can actually get around by just knowing how to clone
  44 the repository and add/remove files from the working copy:</p>
  45
  46 <pre>
  47 cg clone <em>url</em>
  48 cg add <em>file</em>
  49 cg rm <em>file</em>
  50 </pre>
  51
  52 <p>You can get a detailed intro to Git and Cogito <a href="cvs.html">for CVS
  53 users here</a>.</p>
  54
  55 <p>Before running any command the first time, it's recommended that you
  56 at least quickly skim through its manual page. Many of the commands have
  57 very useful and interesting features (that we won't list here) and sometimes
  58 there are some extra notes you might want to know. There's a quick usage
  59 help available for the StGit command using <code class="g">stg help <em>command</em></code>.</p>
  60
  61 <p>To initialize StGit on the current branch of your (probably
  62 freshly cloned) repository, <code class="g">stg init</code>.</p>
  63
  64 <p>To add a new patch to your patch stack, do:</p>
  65
  66 <pre>
  67 stg new invent-some-patch-id
  68 <em>...edit patch description...</em>
  69 <em>...hack hack hack in the tree...</em>
  70 stg refresh
  71 <em>...possibly hack some more...</em>
  72 stg refresh
  73 </pre>
  74
  75 <p>There you go. You can add several patches this way, then use
  76 <code class="g">stg series</code> to list them - the patches
  77 with minus sign are not applied, the patches with plus sign
  78 are applied. You can <em>pop</em> the latest applied patch
  79 using <code class="g">stg pop</code> and apply any of the
  80 yet unapplied patches using <code class="g">stg push</code>.
  81 At any point you can edit the current tree to update your
  82 top currently updated patch - use the refresh command to
  83 record your changes (use <code>-e</code> to update the patch
  84 description as well). <code class="g">stg show</code> will
  85 show the current (or any) patch.</p>
  86
  87 <p>If you want to update your patches to be against the latest
  88 version of a remote branch, use the <code class="g">stg pull</code>
  89 command. It uses the Git pull instead of Cogito pull though, which
  90 you may find inconvenient - in that case, you can do what pull
  91 basically does "manually":</p>
  92
  93 <pre>
  94 stg pop -a
  95 cg update
  96 stg push -a
  97 </pre>
  98
  99 <p>That will pop all the patches, then update your current
 100 branch (which probably has no local changes by then) to the upstream
 101 revision, then push your patches back on top of the new base.
 102 Conflicts may occur - then you need to resolve them and tell
 103 StGit using the <code class="g">stg resolved</code> command
 104 (you may find the <code>-a</code> flag useful) and then update
 105 the patch using <code>stg refresh</code> and resume the patches
 106 pushing by doing <code>stg push -a</code>.
 107
 108 <p>To submit your patches using email, use the <code class="g">stg mail</code>
 109 command. It is very powerful and can submit individual patches,
 110 arbitrary patch series or your whole stack, send covermails and
 111 make your patches followups of other mails. You will probably
 112 want to create simple email templates for your patch. You can
 113 find all the details in the <code class="g">stg help mail</code>
 114 output.</p>
 115
 116 <p>If you have any question or problem which is not obvious from
 117 the documentation, please contact us at the <strong>Git mailing list</strong>
 118 at <a href="mailto:git@vger.kernel.org">git@vger.kernel.org</a>.
 119 We hope you enjoy using Git and Cogito!</p>
 120
 121
 122
 123 <hr />
 124
 125 <div class="footer">
 126         <span class="menu">
 127                 This page is maintained by Petr Baudis. Please email me
 128                 at <a href="mailto:pasky@suse.cz">pasky@suse.cz</a>
 129                 with patches, suggestions and comments.
 130         </span>
 131 </div>
 132
 133 </body>
 134 </html>