Help: evolve

hg evolve [OPTIONS]...

aliases: stabilize, solve

solve troubled changesets in your repository

Modifying history can lead to various types of troubled changesets: orphan, phase-divergent, or content-divergent. The evolve command resolves your troubles by executing one of the following actions:

  • update working copy to a successor
  • rebase an orphan changeset
  • extract the desired changes from a phase-divergent changeset
  • fuse content-divergent changesets back together

If you pass no arguments, evolve works in automatic mode: it will execute a single action to reduce instability related to your working copy. There are two cases for this action. First, if the parent of your working copy is obsolete, evolve updates to the parent's successor. Second, if the working copy parent is not obsolete but has obsolete predecessors, then evolve determines if there is an orphan changeset that can be rebased onto the working copy parent in order to reduce instability. If so, evolve rebases that changeset. If not, evolve refuses to guess your intention, and gives a hint about what you might want to do next.

When "--update" is used, successful evolve operations update the working directory to the newly created changesets. Moreover, an update will always be performed if the current working directory parent is obsolete.

Automatic mode only handles common use cases. For example, it avoids taking action in the case of ambiguity, and it ignores orphan changesets that are not related to your working copy. It also refuses to solve phase-divergent or content-divergent changesets unless you explicitly request such behavior (see below).

Eliminating all instability around your working copy may require multiple invocations of 'hg evolve' if you use "--rev" or "--no-all". Use "--all" (which is the default behavior) to recursively select and evolve all orphan changesets that can be rebased onto the working copy parent. This is more powerful than successive invocations, since "--all" handles ambiguous cases (e.g. orphan changesets with multiple children) by evolving all branches.

When your repository cannot be handled by automatic mode, you might need to use "--rev" to specify a changeset to evolve. For example, if you have an orphan changeset that is not related to the working copy parent, you could use "--rev" to evolve it. Or, if some changeset has multiple orphan children, evolve in automatic mode refuses to guess which one to evolve; you have to use "--rev" in that case.

Alternately, "--any" makes evolve search for the next evolvable changeset regardless of whether it is related to the working copy parent.

You can supply multiple revisions to evolve multiple troubled changesets in a single invocation. In revset terms, "--any" is equivalent to "--rev first(orphan())". "--rev" and "--all" are mutually exclusive, as are "--rev" and "--any".

"hg evolve --any --all" is useful for cleaning up instability across all branches, letting evolve figure out the appropriate order and destination.

When you have troubled changesets that are not orphan, 'hg evolve' refuses to consider them unless you specify the category of trouble you wish to resolve, with "--phase-divergent" or "--content-divergent". These options are currently mutually exclusive with each other and with "--orphan" (the default). You can combine "--phase-divergent" or "--content-divergent" with "--rev", "--all", or "--any".

You can also use the evolve command to list the troubles affecting your repository by using the --list flag. You can choose to display only some categories of troubles with the --orphan, --content-divergent or --phase-divergent flags.

Interrupted

The 'hg evolve' command is an all purpose tool that solves all kinds of instabilities in your repository. Sometimes, instability resolution will lead to merge conflicts that cannot be solved without human intervention (same as 'hg merge'). This can lead to an "interrupted state" where human assistance is requested. There are three things which you can do when you face a similar situation:

  • 'hg evolve --continue': resolve all the conflicts using 'hg resolve' and then run this to continue the interrupted evolve
  • 'hg evolve --stop': stops the current interrupted evolve, keeping all the successful steps, but delaying to resolution of the remaining step for later.
  • 'hg evolve --abort': aborts the interrupted evolve and undoes all the resolution which have happened

(use 'hg help -e evolve' to show help for the evolve extension)

options ([+] can be repeated):

-n --dry-run do not perform actions, just print what would be done
--confirm ask for confirmation before performing the action
-A --any also consider troubled changesets unrelated to current working directory
-r --rev REV [+] solves troubles of these revisions
--phase-divergent solves only phase-divergent changesets
--content-divergent solves only content-divergent changesets
--orphan solves only orphan changesets (default)
-a --all evolve all troubled changesets related to the current working directory and its descendants (default)
--update update to the head of evolved changesets
-c --continue continue an interrupted evolution
--stop stop the interrupted evolution
--abort abort the interrupted evolution
-l --list provide details on troubled changesets in the repo
-t --tool TOOL specify merge tool

global options ([+] can be repeated):

-R --repository REPO repository root directory or name of overlay bundle file
--cwd DIR change working directory
-y --noninteractive do not prompt, automatically pick the first choice for all prompts
-q --quiet suppress output
-v --verbose enable additional output
--color TYPE when to colorize (boolean, always, auto, never, or debug)
--config CONFIG [+] set/override config option (use 'section.name=value')
--debug enable debugging output
--debugger start debugger
--encoding ENCODE set the charset encoding (default: UTF-8)
--encodingmode MODE set the charset encoding mode (default: strict)
--traceback always print a traceback on exception
--time time how long the command takes
--profile print command execution profile
--version output version information and exit
-h --help display help and exit
--hidden consider hidden changesets
--pager TYPE when to paginate (boolean, always, auto, or never) (default: auto)