# HG changeset patch # User Augie Fackler # Date 1341595073 18000 # Node ID 4fb2d3d16743918b6f7b84fea31e48d20ec2896b # Parent 0a48f3d54543dceab4e90c8755802d775f6d5b3b histedit: add extension docstring from external README Made a couple of tweaks to try and fit better with the hg docstring style and fix up some ReST errors in the README. diff -r 0a48f3d54543 -r 4fb2d3d16743 hgext/histedit.py --- a/hgext/histedit.py Fri Jul 06 11:39:02 2012 -0500 +++ b/hgext/histedit.py Fri Jul 06 12:17:53 2012 -0500 @@ -4,10 +4,142 @@ # # This software may be used and distributed according to the terms of the # GNU General Public License version 2 or any later version. -"""Interactive history editing. +"""interactive history editing + +With this extension installed, Mercurial gains one new command: histedit. Usage +is as follows, assuming the following history:: + + @ 3[tip] 7c2fd3b9020c 2009-04-27 18:04 -0500 durin42 + | Add delta + | + o 2 030b686bedc4 2009-04-27 18:04 -0500 durin42 + | Add gamma + | + o 1 c561b4e977df 2009-04-27 18:04 -0500 durin42 + | Add beta + | + o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42 + Add alpha + +If you were to run ``hg histedit c561b4e977df``, you would see the following +file open in your editor:: + + pick c561b4e977df Add beta + pick 030b686bedc4 Add gamma + pick 7c2fd3b9020c Add delta + + # Edit history between 633536316234 and 7c2fd3b9020c + # + # Commands: + # p, pick = use commit + # e, edit = use commit, but stop for amending + # f, fold = use commit, but fold into previous commit + # d, drop = remove commit from history + # m, mess = edit message without changing commit content + # + 0 files updated, 0 files merged, 0 files removed, 0 files unresolved + +In this file, lines beginning with ``#`` are ignored. You must specify a rule +for each revision in your history. For example, if you had meant to add gamma +before beta, and then wanted to add delta in the same revision as beta, you +would reorganize the file to look like this:: + + pick 030b686bedc4 Add gamma + pick c561b4e977df Add beta + fold 7c2fd3b9020c Add delta + + # Edit history between 633536316234 and 7c2fd3b9020c + # + # Commands: + # p, pick = use commit + # e, edit = use commit, but stop for amending + # f, fold = use commit, but fold into previous commit + # d, drop = remove commit from history + # m, mess = edit message without changing commit content + # + 0 files updated, 0 files merged, 0 files removed, 0 files unresolved + +At which point you close the editor and ``histedit`` starts working. When you +specify a ``fold`` operation, ``histedit`` will open an editor when it folds +those revisions together, offering you a chance to clean up the commit message:: + + Add beta + *** + Add delta -Inspired by git rebase --interactive. +Edit the commit message to your liking, then close the editor. For +this example, let's assume that the commit message was changed to +``Add beta and delta.`` After histedit has run and had a chance to +remove any old or temporary revisions it needed, the history looks +like this:: + + @ 2[tip] 989b4d060121 2009-04-27 18:04 -0500 durin42 + | Add beta and delta. + | + o 1 081603921c3f 2009-04-27 18:04 -0500 durin42 + | Add gamma + | + o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42 + Add alpha + +Note that ``histedit`` does *not* remove any revisions (even its own temporary +ones) until after it has completed all the editing operations, so it will +probably perform several strip operations when it's done. For the above example, +it had to run strip twice. Strip can be slow depending on a variety of factors, +so you might need to be a little patient. You can choose to keep the original +revisions by passing the ``--keep`` flag. + +The ``edit`` operation will drop you back to a command prompt, +allowing you to edit files freely, or even use ``hg record`` to commit +some changes as a separate commit. When you're done, any remaining +uncommitted changes will be committed as well. When done, run ``hg +histedit --continue`` to finish this step. You'll be prompted for a +new commit message, but the default commit message will be the +original message for the ``edit`` ed revision. + +The ``message`` operation will give you a chance to revise a commit +message without changing the contents. It's a shortcut for doing +``edit`` immediately followed by `hg histedit --continue``. + +If ``histedit`` encounters a conflict when moving a revision (while +handling ``pick`` or ``fold``), it'll stop in a similar manner to +``edit`` with the difference that it won't prompt you for a commit +message when done. If you decide at this point that you don't like how +much work it will be to rearrange history, or that you made a mistake, +you can use ``hg histedit --abort`` to abandon the new changes you +have made and return to the state before you attempted to edit your +history. + +If we clone the example repository above and add three more changes, such that +we have the following history:: + + @ 6[tip] 038383181893 2009-04-27 18:04 -0500 stefan + | Add theta + | + o 5 140988835471 2009-04-27 18:04 -0500 stefan + | Add eta + | + o 4 122930637314 2009-04-27 18:04 -0500 stefan + | Add zeta + | + o 3 836302820282 2009-04-27 18:04 -0500 stefan + | Add epsilon + | + o 2 989b4d060121 2009-04-27 18:04 -0500 durin42 + | Add beta and delta. + | + o 1 081603921c3f 2009-04-27 18:04 -0500 durin42 + | Add gamma + | + o 0 d8d2fcd0e319 2009-04-27 18:04 -0500 durin42 + Add alpha + +If you run ``hg histedit --outgoing`` on the clone then it is the same +as running ``hg histedit 836302820282``. If you need plan to push to a +repository that Mercurial does not detect to be related to the source +repo, you can add a ``--force`` option. """ + try: import cPickle as pickle except ImportError: @@ -243,7 +375,7 @@ 'mess': message, } def histedit(ui, repo, *parent, **opts): - """hg histedit + """interactively edit changeset history """ # TODO only abort if we try and histedit mq patches, not just # blanket if mq patches are applied somewhere @@ -561,6 +693,6 @@ 'force outgoing even for unrelated repositories')), ('r', 'rev', [], _('first revision to be edited')), ], - __doc__, + _("[PARENT]"), ), }