Commits

Augie Fackler committed 5336dd2

Much-overdue documentation.

Comments (0)

Files changed (1)

+.. -*-restructuredtext-*-
+
+============
+histedit
+============
+Interactive history editing for Mercurial.
+
+**Warning**: ``histedit`` alters history! It probably won't destroy your data,
+but that chance exists. You should *never* edit already-published history. 
+Caveat Emptor.
+
+**Warning 2**: If you ``drop`` a change, it's *gone* **forever** (unless you passed ``--keep``).
+You've been warned!
+
+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
+ #
+ 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
+ #
+ 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
+
+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.
+
+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.