StGit tutorial ############## StGit is a command-line application that provides functionality similar to htmllink:http://savannah.nongnu.org/projects/quilt/[Quilt] (i.e. pushing/popping patches to/from a stack), but using Git instead of +diff+ and +patch+. StGit stores its patches in a Git repository as normal Git commits, and provides a number of commands to manipulate them in various ways. This tutorial assumes you are already familiar with the basics of Git (for example, branches, commits, and conflicts). For more information on Git, see manlink:git[1] or htmllink:http://git.or.cz/[the Git home page]. Help ==== For a full list of StGit commands: $ stg help For quick help on individual subcommands: $ stg help For more extensive help on a subcommand: $ man stg- (The documentation is also available in htmllink:stg.html[HTML format].) Getting started =============== StGit is not a stand-alone program -- it operates on a Git repository that you have already created, using +git init+ or +git clone+. So get one of those; if you don't have one at hand, try for example $ git clone http://homepage.ntlworld.com/cmarinas/stgit.git $ cd stgit Before you can create StGit patches, you have to run stglink:init[]: $ stg init This initializes the StGit metadata for the current branch. (So if you want to have StGit patches in another branch too, you need to run +stg init+ again in that branch.) NOTE: As a shortcut, stglink:clone[] will run +git clone+ followed by +stg init+ for you. Creating a patch ---------------- Now we're ready to create our first patch: $ stg new my-first-patch This will create a patch called +my-first-patch+, and open an editor to let you edit the patch's commit message. (If you don't give a name on the command line, StGit will make one up based on the first line of the commit message.) This patch is empty, as stglink:show[] will tell you: $ stg show But it won't stay that way for long! Open one of the files in your favorite text editor, change something, and save. You now have some local changes in your tree: $ stg status M stgit/main.py Then stgsublink:refresh[] the patch: $ stg refresh And voilà -- the patch is no longer empty: $ stg show commit 3de32068c600d40d8af2a9cf1f1c762570ae9610 Author: Audrey U. Thor Date: Sat Oct 4 16:10:54 2008 +0200 Tell the world that I've made a patch diff --git a/stgit/main.py b/stgit/main.py index e324179..6398958 100644 --- a/stgit/main.py +++ b/stgit/main.py @@ -171,6 +171,7 @@ def _main(): sys.exit(ret or utils.STGIT_SUCCESS) def main(): + print 'My first patch!' try: _main() finally: (I'm assuming you're already familiar with htmllink:http://en.wikipedia.org/wiki/Diff#Unified_format[unified diff] patches like this from Git, but it's really quite simple; in this example, I've added the +$$print 'My first patch!'$$+ line to the file +stgit/main.py+, at around line 171.) Since the patch is also a regular Git commit, you can also look at it with regular Git tools such as manlink:gitk[]. Creating another patch ---------------------- We want to make another improvement, so let's create a new patch for it: $ echo 'Audrey U. Thor' > AUTHORS $ stg new credit --message 'Give me some credit' $ stg refresh Note that we can give the commit message on the command line, and that it doesn't matter whether we run stglink:new[] before or after we edit the files. So now we have two patches: $ stg series --description + my-first-patch # This is my first patch > credit # Give me some credit stglink:series[] lists the patches from bottom to top; +$$+$$+ means that a patch is 'applied', and +>+ that it is the 'current', or topmost, patch. If we want to make further changes to the topmost patch, we just edit the files and run +stg refresh+. But what if we wanted to change +my-first-patch+? The simplest way is to stgsublink:pop[] the +credit+ patch, so that +my-first-patch+ becomes topmost again: $ stg pop credit Checking for changes in the working directory ... done Popping patch "credit" ... done Now at patch "my-first-patch" $ stg series --description > my-first-patch # This is my first patch - credit # Give me some credit stglink:series[] now shows that +my-first-patch+ is topmost again, which means that stglink:refresh[] will update it with any changes we make. The minus sign says that +credit+ is 'unapplied' -- this means that it's been temporarily put aside. If you look at the +AUTHORS+ file, you'll see that our change to it is gone; and tools such as manlink:gitk[] will not show it, because it's been edited out of the Git history. But it's just one stglink:push[] command away from being restored: $ stg push credit Checking for changes in the working directory ... done Fast-forwarded patch "credit" Now at patch "credit" NOTE: You can omit the patch name argument to stglink:push[] and stglink:pop[]. If you do, you will push the next unapplied patch, and pop the topmost patch, respectively. NOTE: There are at least two more ways to update a non-topmost patch. One is to use stglink:refresh[] with the +$$--patch$$+ flag, the other to create a new patch for the update and then merge it into the other patch with stglink:coalesce[]. Keeping commit messages up to date ---------------------------------- Since StGit is all about creating readable Git history (or a readable patch series, which is essentially the same thing), one thing you'll want to pay attention to is the commit messages of your patches. stglink:new[] asks you for a commit message when you create a new patch, but as time goes by and you refresh the patch again and again, chances are that the original commit message isn't quite correct anymore. Fortunately, editing the commit message is very easy: $ stg edit In addition to stglink:edit[], you can also give the +$$--edit$$+ flag to stglink:refresh[] -- that way, you get to change the commit message and update the patch at the same time. Use whichever feels most natural to you. NOTE: stglink:edit[] has a +$$--diff$$+ flag, which gives you the diff text and not just the commit message in your editor. Be aware, though, that if you change the diff so that it no longer applies, the edit will be saved to a file instead of being carried out. If you're not comfortable editing diffs, just treat +$$--diff$$+ as a way to get to 'see' the diff while you edit the commit message. If the patch changes considerably, it might even deserve a new name. stglink:rename[] is your friend there. Conflicts --------- Normally, when you pop a patch, change something, and then later push it again, StGit sorts out everything for you automatically. For example, let's create two patches that modify different files: $ stg clone http://homepage.ntlworld.com/cmarinas/stgit.git stgit $ cd stgit $ stg new first --message 'First patch' $ echo '- Do something' >> TODO $ stg refresh $ stg new second --message 'Second patch' $ echo '- Install something' >> INSTALL $ stg refresh then pop them both: $ stg pop --all and then push them in the opposite order: $ stg push second first $ stg series + second > first StGit had no problems reordering these patches for us, since they didn't touch the same file. But it would have worked just fine even if they had touched the same file, as long as they didn't change the same part of the file. But what if they did? Let's find out. $ stg pop Checking for changes in the working directory ... done Popping patch "first" ... done Now at patch "second" $ echo '- Do something else' >> TODO $ stg refresh Now, both patches add a new line at the end of +TODO+. So what happens when we try to have them both applied? $ stg push Pushing patch "first" ... CONFLICT (content): Merge conflict in TODO Error: The merge failed during "push". Revert the operation with "stg undo". stg push: 1 conflict(s) StGit is telling us that it couldn't figure out how to push +first+ on top of +second+, now that they both modify +TODO+. We can take a look at the situation with stglink:status[]: $ stg status ? TODO.ancestor ? TODO.current ? TODO.patched C TODO As we were told by stglink:push[], the conflict is in the file +TODO+. (If the patch was bigger and touched multiple files, they would all be listed here; prefixed with +C+ if they had conflicts, and +M+ if StGit managed to automatically resolve everything in the file.) NOTE: +TODO.ancestor+, +TODO.current+, and +TODO.patched+ are the three versions of the file that StGit tried to merge. The +.current+ file is the version before the patch was applied, +.patched+ is the version in the patch we tried to push, and +.ancestor+ the version that contains neither of the added lines. At this point, we have two options: 1. Undo the failed merge with stglink:undo[]. (Remember to use the +$$--hard$$+ flag, since the unresolved conflict means the worktree is not clean.) 2. Manually resolve the conflict. To resolve the conflict, open +TODO+ in your favorite editor. It ends like this: ---------------------------------------------------------------------- - numeric shortcuts for naming patches near top (eg. +1, -2) - (config?) parameter for number of patches included by "series -s" <<<<<<< current:TODO - Do something else ======= - Do something >>>>>>> patched:TODO ---------------------------------------------------------------------- The 'conflict markers' +<<<<<<<+, +=======+, and +>>>>>>>+ indicate which lines were already there (+current+) and which were added by the patch (+patched+). Edit the file so that it looks like it should; in this case, we want something like this: ---------------------------------------------------------------------- - numeric shortcuts for naming patches near top (eg. +1, -2) - (config?) parameter for number of patches included by "series -s" - Do something - Do something else ---------------------------------------------------------------------- Note that ``looks like it should'' includes removing the conflict markers. Now that we've resolved the conflict, we just need to tell StGit about it: $ stg resolved TODO $ stg status M TODO +TODO+ is listed as being modified, not in conflict. And we know from before how to deal with modified files: $ stg refresh The conflict is now resolved. We can see that +first+ now looks a little different; it no longer adds a line at the end of the file: $ stg show commit 8e3ae5f6fa6e9a5f831353524da5e0b91727338e Author: Audrey U. Thor Date: Sun Oct 5 14:43:42 2008 +0200 First patch diff --git a/TODO b/TODO index 812d236..4ef3841 100644 --- a/TODO +++ b/TODO @@ -24,4 +24,5 @@ The future, when time allows or if someone else does them: they have scripts for moving the changes in one to the others) - numeric shortcuts for naming patches near top (eg. +1, -2) - (config?) parameter for number of patches included by "series -s" +- Do something - Do something else Workflow: Development branch ============================ One common use of StGit is to ``polish'' a Git branch before you publish it for others to see. Such history falsification can often be a 'good' thing -- when you (or someone else) needs to look at what you did six months later, you are not really interested in all the false starts and the steps needed to corect them. What you want is the final solution, presented in a way that makes it easy to read and understand. Of course, there are limits. Editing the last few days' worth of history is probably a good idea; editing the last few months' probably isn't. A rule of thumb might be to not mess with history old enough that you don't remember the details anymore. And rewriting history that you have published for others to see (and base their own work on) usually just makes everyone more confused, not less. So, let's take a concrete example. Say that you're hacking on StGit, and have made several Git commits as your work progressed, with commit messages such as ``Improve the snarfle cache'', ``Remove debug printout'', ``New snarfle cache test'', ``Oops, spell function name correctly'', ``Fix documentation error'', and ``More snarfle cache''. Now, this is the actual history, but for obvious reasons, this isn't the kind of history you'd ideally want to find when you six months from now try to figure out exactly where that elusive snarfle cache bug was introduced. So let's turn this into the history we can be proud of. The first step is to make StGit patches out of all those Git commits: $ stg uncommit --number 6 Uncommitting 6 patches ... Now at patch "more-snarfle-cache" done $ stg series --description + improve-the-snarfle-cache # Improve the snarfle cache + remove-debug-printout # Remove debug printout + new-snarfle-cache-test # New snarfle cache test + oops-spell-function-name-corre # Oops, spell function name correctly + fix-documentation-error # Fix documentation error > more-snarfle-cache # More snarfle cache As you can see, stglink:uncommit[] adds StGit metadata to the last few Git commits, turning them into StGit patches so that we can do stuff with them. NOTE: With the +$$--number$$+ flag, stglink:uncommit[] uncommits that many commits and generates names for them based on their commit messages. If you like, you can instead list the patch names you want on the command line. At this point, there are a number of things we could do: * Continue developing, and take advantage of e.g. stglink:goto[] or +stg refresh $$--patch$$+ to stick updates in the right patch to begin with. * Use e.g. stglink:float[], stglink:sink[], stglink:push[], and stglink:pop[] to reorder patches. * Use stglink:coalesce[] to merge two or more patches into one. stgsublink:coalesce[] pushes and pops so that the patches to be merged are consecutive and unrelated patches aren't in the way, then makes one big patch out of the patches to be merged, and finally pushes the other patches back. + Of course, as always when there is pushing involved, there is the possibility of conflicts. If a push results in a conflict, the operation will be halted, and we'll be given the option of either resolving the conflict or undoing. Once we feel that the history is as good as it's going to get, we can remove the StGit metadata, turning the patches back into regular Git commits again: $ stg commit --all TIP: stglink:commit[] can also commit specific patches (named on the command line), leaving the rest alone. This can be used to retire patches as they mature, while keeping the newer and more volatile patches as patches. Workflow: Tracking branch ========================= Rebasing a patch series ----------------------- TODO:: rebase, ... Getting patches upstream ------------------------ TODO:: export, mail, ... Importing patches ----------------- TODO:: import, ... Other stuff that needs to be placed somewhere ============================================= Undo ---- TODO:: undo, redo, log, reset Interoperating with Git ----------------------- TODO:: * git commit + repair * git reset HEAD~n + repair * don't do git rebase or git merge, because it won't work Patch stuff ----------- TODO:: This section needs revising. I've only fixed the formatting. Most of it should go under "Workflow: Tracking branch" As mentioned in the introduction, StGit 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 StGit patches into normal textual diffs that can be applied with the GNU patch command. stglink:diff[] is a powerful way to generate and view textual diffs of patches managed by StGit. To view a diff of the topmost patch: $ stg diff -r / Observe that this does not show any changes in the working directory that have not been saved by a stgsublink:refresh[]. To view just the changes you've made since the last refresh, use: $ stg diff -r /top If you want to see the changes made by the patch combined with any unsaved changes in the working directory, try: $ stg diff -r /bottom You can also show the changes to any patch in your stack with: $ stg diff -r / Use this command to view all the changes in your stack up through the current patch: $ stg diff -r base stglink:diff[] supports a number of other features that are very useful. Be sure to take a look at the help information for this command. To convert your StGit patches into patch files: $ stg export [--range=[[:]]] [] stglink:export[] supports options to automatically number the patches (+-n+) or add the +.diff+ extension (+-d+). If you don't tell stgsublink:export[] where to put the patches, it will create directory named +patch-+ in your current directory, and store the patches there. To e-mail a patch or range of patches: $ stg mail [--to=...] (--all | --range=[[:]] | ) stglink:mail[] has a lot of options, so read the output of +stg mail -h+ for more information. You can also import an existing GNU diff patch file as a new StGit patch with a single command. stglink:import[] will automatically parse through the patch file and extract a patch description. Use: $ stg import [] This is the equivalent of $ stg new $ patch -i $ stg refresh -e Sometimes the patch file won't apply cleanly. In that case, stglink:import[] will leave you with an empty StGit patch, to which you then apply the patch file by hand using "patch -i" and your favorite editor. To merge a GNU diff file (defaulting to the standard input) into the topmost patch: $ stg fold [] This command supports a +$$--threeway$$+ option which applies the patch onto the bottom of the topmost one and performs a three-way merge. Templates --------- TODO:: This section needs revising. I've only fixed the formatting. stglink:export[] and stglink:mail[] use templates for generating the patch files or e-mails. The default templates are installed under +/share/stgit/templates/+ and, combined with the extra options available for these commands, should be enough for most users. The template format uses the standard Python string formatting rules. The variables available are listed in the the manual pages for each command. stglink:mail[] can also send an initial 'cover' e-mail for which there is no default template. The +/share/stgit/examples/firstmail.tmpl+ file can be used as an example. 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.