histedit

Description

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 c561b4e977df and 7c2fd3b9020c
#
# Commits are listed from least to most recent
#
# Commands:
#  p, pick = use commit
#  e, edit = use commit, but stop for amending
#  f, fold = use commit, but combine it with the one above
#  r, roll = like fold, but discard this commit's description and date
#  d, drop = remove commit from history
#  m, mess = edit commit message without changing commit content
#  b, base = checkout changeset and apply further changesets from there
#

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 c561b4e977df and 7c2fd3b9020c
#
# Commits are listed from least to most recent
#
# Commands:
#  p, pick = use commit
#  e, edit = use commit, but stop for amending
#  f, fold = use commit, but combine it with the one above
#  r, roll = like fold, but discard this commit's description and date
#  d, drop = remove commit from history
#  m, mess = edit commit message without changing commit content
#  b, base = checkout changeset and apply further changesets from there
#

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. The date used for the commit will be the later of the two commits' dates. 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. If there are uncommitted changes, you'll be prompted for a new commit message, but the default commit message will be the original message for the edit ed revision, and the date of the original commit will be preserved.

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 histedit-ed example repository above and add four 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.

Config

Histedit rule lines are truncated to 80 characters by default. You can customize this behavior by setting a different length in your configuration file:

[histedit]
linelen = 120      # truncate rule lines at 120 characters

The summary of a change can be customized as well:

[histedit]
summary-template = '{rev} {bookmarks} {desc|firstline}'

The customized summary should be kept short enough that rule lines will fit in the configured line length. See above if that requires customization.

hg histedit attempts to automatically choose an appropriate base revision to use. To change which base revision is used, define a revset in your configuration file:

[histedit]
defaultrev = only(.) & draft()

By default each edited revision needs to be present in histedit commands. To remove revision you need to use drop operation. You can configure the drop to be implicit for missing commits by adding:

[histedit]
dropmissing = True

By default, histedit will close the transaction after each action. For performance purposes, you can configure histedit to use a single transaction across the entire histedit. WARNING: This setting introduces a significant risk of losing the work you've done in a histedit if the histedit aborts unexpectedly:

[histedit]
singletransaction = True

Commands

histedit

interactively edit changeset history:

hg histedit [OPTIONS] ([ANCESTOR] | --outgoing [URL])

This command lets you edit a linear series of changesets (up to and including the working directory, which should be clean). You can:

  • pick to [re]order a changeset
  • drop to omit changeset
  • mess to reword the changeset commit message
  • fold to combine it with the preceding changeset (using the later date)
  • roll like fold, but discarding this commit's description and date
  • edit to edit this changeset (preserving date)
  • base to checkout changeset and apply further changesets from there

There are a number of ways to select the root changeset:

  • Specify ANCESTOR directly
  • Use --outgoing -- it will be the first linear changeset not included in destination. (See hg help config.paths.default-push)
  • Otherwise, the value from the "histedit.defaultrev" config option is used as a revset to select the base revision when ANCESTOR is not specified. The first revision returned by the revset is used. By default, this selects the editable history that is unique to the ancestry of the working directory.

If you use --outgoing, this command will abort if there are ambiguous outgoing revisions. For example, if there are multiple branches containing outgoing revisions.

Use "min(outgoing() and ::.)" or similar revset specification instead of --outgoing to specify edit target revision exactly in such ambiguous situation. See hg help revsets for detail about selecting revisions.

Examples:

  • A number of changes have been made. Revision 3 is no longer needed.

    Start history editing from revision 3:

    hg histedit -r 3
    

    An editor opens, containing the list of revisions, with specific actions specified:

    pick 5339bf82f0ca 3 Zworgle the foobar
    pick 8ef592ce7cc4 4 Bedazzle the zerlog
    pick 0a9639fcda9d 5 Morgify the cromulancy
    

    Additional information about the possible actions to take appears below the list of revisions.

    To remove revision 3 from the history, its action (at the beginning of the relevant line) is changed to 'drop':

    drop 5339bf82f0ca 3 Zworgle the foobar
    pick 8ef592ce7cc4 4 Bedazzle the zerlog
    pick 0a9639fcda9d 5 Morgify the cromulancy
    
  • A number of changes have been made. Revision 2 and 4 need to be swapped.

    Start history editing from revision 2:

    hg histedit -r 2
    

    An editor opens, containing the list of revisions, with specific actions specified:

    pick 252a1af424ad 2 Blorb a morgwazzle
    pick 5339bf82f0ca 3 Zworgle the foobar
    pick 8ef592ce7cc4 4 Bedazzle the zerlog
    

    To swap revision 2 and 4, its lines are swapped in the editor:

    pick 8ef592ce7cc4 4 Bedazzle the zerlog
    pick 5339bf82f0ca 3 Zworgle the foobar
    pick 252a1af424ad 2 Blorb a morgwazzle
    

Returns 0 on success, 1 if user intervention is required (not only for intentional "edit" command, but also for resolving unexpected conflicts).

Options:

--commands <FILE>
 read history edits from the specified file
-c, --continue continue an edit already in progress
--edit-plan edit remaining actions list
-k, --keep don't strip old nodes after edit is complete
--abort abort an edit in progress
-o, --outgoing changesets not found in destination
-f, --force force outgoing even for unrelated repositories
-r, --rev <REV[+]>
 first revision to be edited
-T, --template <TEMPLATE>
 display with template

[+] marked option can be specified multiple times