X-Git-Url: https://git.distorted.org.uk/~mdw/stgit/blobdiff_plain/9ab06b9858bbb0196867506724a8d74c8f39e113..a0689e114cdccceedc366e1bfa5be00ad62b2a31:/Documentation/tutorial.txt diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 4aa7629..6143074 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -2,7 +2,7 @@ StGit tutorial ############## StGit is a command-line application that provides functionality -similar to htmllink:http://savannah.nongnu.org/projects/quilt/[Quilt] +similar to link: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 @@ -10,7 +10,7 @@ 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 +on Git, see linkman:git[1] or link:http://git.or.cz/[the Git home page]. @@ -29,7 +29,7 @@ For more extensive help on a subcommand: $ man stg- -(The documentation is also available in htmllink:stg.html[HTML +(The documentation is also available in link:stg.html[HTML format].) @@ -40,7 +40,7 @@ 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 + $ git clone git://repo.or.cz/stgit.git $ cd stgit Before you can create StGit patches, you have to run linkstg:init[]: @@ -104,13 +104,13 @@ And voilà -- the patch is no longer empty: finally: (I'm assuming you're already familiar with -htmllink:http://en.wikipedia.org/wiki/Diff#Unified_format[unified +link: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[]. +with regular Git tools such as linkman:gitk[]. Creating another patch ---------------------- @@ -156,7 +156,7 @@ 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 +linkman:gitk[] will not show it, because it's been edited out of the Git history. But it's just one linkstg:push[] command away from being restored: @@ -258,9 +258,6 @@ top of +second+, now that they both modify +TODO+. We can take a look at the situation with linkstg:status[]: $ stg status - ? TODO.ancestor - ? TODO.current - ? TODO.patched C TODO As we were told by linkstg:push[], the conflict is in the file +TODO+. @@ -268,19 +265,14 @@ As we were told by linkstg:push[], the conflict is in the file +TODO+. 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 linkstg:undo[]. (Remember to use the +$$--hard$$+ flag, since the unresolved conflict means the worktree is not clean.) - 2. Manually resolve the conflict. + 2. Manually resolve the conflict (editing the file directly followed + by +git add+ or using +git mergetool+.) To resolve the conflict, open +TODO+ in your favorite editor. It ends like this: @@ -832,3 +824,206 @@ which there is no default template. The 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. + +Emacs +===== + +StGit comes with an Emacs mode, +stgit-mode+, supporting Emacs +versions 22 and later. + +To start using it, add the +stgit/contrib+ directory to your Emacs +load-path and run +(require 'stgit)+. For example, you can add the +following to your +.emacs+ file: + +---------------------------------------------------------------------- +(add-to-list 'load-path "/path/to/stgit/contrib") +(require 'stgit) +---------------------------------------------------------------------- + +Start +stgit-mode+ using +M-x stgit+ and select the directory where +the source code you want to use StGit on can be found. If StGit has +not been initialized in this directory yet, you will need to run +M-x +stgit-init+ before you continue. + +The +stgit-mode+ buffer (usually named +$$*stgit*$$+) has the +following layout: + +---------------------------------------------------------------------- +Branch: name-of-branch + ++ The first applied patch ++ Another applied patch +> The topmost patch + Index + + Work Tree + +- An unapplied patch +- Another unapplied patch +-- +---------------------------------------------------------------------- + +The above means that the active branch name is +name-of-branch+ and it +contains five patches, three of which are applied. The git index and +working tree contain no (modified) files. + +Basic Commands +-------------- + +To get help, press +h+. This opens a new buffer which lists all +commands supported in +stgit-mode+. Also, if you have the menu bar +enabled (toggled using +M-x menu-bar-mode+), a new menu entry called ++StGit+ will appear, from which you can run several StGit commands. As +the menu should be self-explanatory, the rest of this tutorial will +focus on available keyboard commands. + +Move the point (cursor) between lines using +C-p+ and +C-n+, or +between patches using +p+ and +n+. + +You can linkstgsub:undo[] and linkstgsub:redo[] StGit commands using ++C-/+ and +C-c C-/+, respectively. + +Creating New Patches +-------------------- + +If you want to create a new patch, first make some changes that should +go into it. As you save a file which is Git-controlled, it will appear +as a modification in the +Work Tree+ section: + +---------------------------------------------------------------------- + Work Tree + Modified foo.txt +---------------------------------------------------------------------- + +To create a new patch based on the changes in the index or, if it +contains no changes, the working tree, press +c+. This opens a new +buffer where you can enter the patch description. When you are done, +press +C-c C-c+. Your new patch will now show up in the +$$*stgit*$$+ +buffer, and the working tree will no longer contain any modifications: + +---------------------------------------------------------------------- ++ The topmost patch +> First line of your new description + Index + + Work Tree + +---------------------------------------------------------------------- + +As you make additional changes in your files, and want to include them +in the topmost patch, press +r+, which runs linkstg:refresh[]. If you +want to add the changes to a patch which is not topmost, move the +point to the line of that patch and press +C-u r+. + +Inspecting Patches +------------------ + +To see what a particular patch contains, you can move the point +(cursor) to the line of that patch, and press +RET+ (Enter). This will +"expand" the patch and show which files it changes: + +---------------------------------------------------------------------- ++ My patch + Modified foo.txt + Deleted bar.c +---------------------------------------------------------------------- + +You can press +=+, which will show the diff of that patch or file in a +new buffer. With a prefix argument (+C-u =+), the diff will not show +changes in whitespace. + +To visit (open) a modified file in another Emacs window, press +o+ on +that line. +RET+ will visit it in the current window. + +Changing the Patch Series +------------------------- + +You can linkstgsub:push[] and linkstgsub:pop[] patches using +>+ +(pushes the topmost unapplied patch onto the stack) and +<+ (pops the +topmost applied patch off the stack). + +By moving the point to a particular patch and pressing +P+ (+S-p+) +you either (if it already was applied) pop that patch off the stack, +or (if it was unapplied) push it onto the stack. + +You can move patches by first marking one or more using +m+. Then, +move the point to where in the series you want these patches to move, +and press +M+. Use +DEL+ or +u+ to remove a mark. + +You can also combine (linkstgsub:squash[]) two or more patches by +marking them and pressing +S+ (+S-s+). This will open a new buffer +where you can edit the patch description of the new, combined, patch. +When done, press +C-c C-c+, and the topmost of the marked patches will +be replaced in the stack by one combined patch. + +You can linkstgsub:delete[] a patch by moving to its line and pressing ++D+. If you press +C-u D+, the contents of the patch will be spilled +to the index. + +To linkstgsub:edit[] the description of a patch, press +e+. This opens +the patch description in a new buffer. Press +C-c C-c+ when you are +done editing the patch. + +These operations may result in merge conflicts; more about that later. + +Patch Names +----------- + +By default, the patch description is shown but not the patch names. +You can toggle showing the names using +t n+. To rename a patch, press ++C-c C-r+. + +Using the Index and Working Tree +-------------------------------- + +You can move a changed file between the index and the working tree +using +i+. This is useful if your working tree contains a number of +changes and you want to create or refresh a patch using only some of +the changed file. Once you have the correct set of files in the index, +use +c+ to create or +r+ to refresh patches using only the files in +the index. + +If you want to revert a change in either the index or the working +tree, move the point to that line and press +U+. If you press +U+ on +the +Index+ or +Work Tree+ lines, all the changes in the index or +working tree will be reverted. + +Branches +-------- + +You can switch to another linkstgsub:branch[] by pressing +B+. If you +type the name of a branch that does not exist, you will be asked +whether to create one. The new branch will be based off the current ++HEAD+. + +Use +C-c C-b+ to linkstgsub:rebase[] the current branch. It will +default to rebasing to the +git config+ setting for ++branch._branch_.stgit.parentbranch+. + +Merge Conflicts +--------------- + +If an operation resulted in a merge conflict, the files with conflicts +will show as +Unmerged+ in the +$$*stgit*$$+ buffer. + +To handle the conflicts, you can linkstgsub:undo[] the operation that +caused the conflict using +C-u C-/+. Note the +C-u+ prefix, which will +tell the undo operation to continue despite the index or working tree +containing changes. + +If you instead want to resovle the changes, you must first edit the +files with conflicts to make sure they are in the correct state. Once +you have done this, press +R+ on the line of that file, which will +remove the +Unmerged+ flag. Once all conflicts have been resolved, you +can continue working as normal, for example by refreshing the patch +that had the conflict. + +To investigate the reason of conflicts, you can use the +d b+, +d o+, +and +d t+ commands to, respectively, show the diffs against the merge +base, our branch, or their branch. +d c+ shows a combined diff. See +linkman:git-diff[1] for more information about these commands. + +A more powerful tool to resolve conflicts is the Emacs +smerge-mode+. +To start using it to resolve a conflict, press +d m+. It is outside +the scope of this tutorial to explain how to use it, but press +q+ to +leave +smerge-mode+.