# evolve extension for Mercurial

## Evolve Commands Reference

## amend

    hg amend [OPTION]... [FILE]...

    aliases: refresh

    combine a changeset with updates and replace it with a new one

        Commits a new changeset incorporating both the changes to the given files
        and all the changes from the current parent changeset into the repository.

        See 'hg commit' for details about committing changes.

        If you don't specify -m, the parent's message will be reused.

        If --extract is specified, the behavior of 'hg amend' is reversed: Changes
        to selected files in the checked out revision appear again as uncommitted
        changed in the working directory.

        Returns 0 on success, 1 if nothing changed.

    options ([+] can be repeated):

     -A --addremove           mark new/missing files as added/removed before
                              committing
     -a --all                 match all files
     -e --edit                invoke editor on commit messages
        --extract             extract changes from the commit to the working copy
        --patch               make changes to wdir parent by editing patch
        --close-branch        mark a branch as closed, hiding it from the branch
                              list
     -s --secret              use the secret phase for committing
     -n --note TEXT           store a note on amend
     -I --include PATTERN [+] include names matching the given patterns
     -X --exclude PATTERN [+] exclude names matching the given patterns
     -m --message TEXT        use text as commit message
     -l --logfile FILE        read commit message from file
     -d --date DATE           record the specified date as commit date
     -u --user USER           record the specified user as committer
     -D --current-date        record the current date as commit date
     -U --current-user        record the current user as committer
     -i --interactive         use interactive mode

    (some details hidden, use --verbose to show complete 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

    (some details hidden, use --verbose to show complete help)

## fold

    hg fold [OPTION]... [-r] REV...

    aliases: squash

    fold multiple revisions into a single one

        With --from, folds all the revisions linearly between the given revisions
        and the parent of the working directory.

        With --exact, folds only the specified revisions while ignoring the parent
        of the working directory. In this case, the given revisions must form a
        linear unbroken chain.

    options ([+] can be repeated):

     -r --rev REV [+]  revision to fold
        --exact        only fold specified revisions
        --from         fold revisions linearly to working copy parent
     -n --note TEXT    store a note on fold
     -m --message TEXT use text as commit message
     -l --logfile FILE read commit message from file
     -d --date DATE    record the specified date as commit date
     -u --user USER    record the specified user as committer
     -D --current-date record the current date as commit date
     -U --current-user record the current user as committer

    (some details hidden, use --verbose to show complete help)

## metaedit

    hg metaedit [OPTION]... [[-r] REV]...

    edit commit information

        Edits the commit information for the specified revisions. By default,
        edits commit information for the working directory parent.

        With --fold, also folds multiple revisions into one if necessary. In this
        case, the given revisions must form a linear unbroken chain.

    options ([+] can be repeated):

     -r --rev REV [+]  revision to edit
        --fold         also fold specified revisions into one
     -n --note TEXT    store a note on metaedit
     -m --message TEXT use text as commit message
     -l --logfile FILE read commit message from file
     -d --date DATE    record the specified date as commit date
     -u --user USER    record the specified user as committer
     -D --current-date record the current date as commit date
     -U --current-user record the current user as committer

    (some details hidden, use --verbose to show complete help)

## next

    hg next [OPTION]...

    update to next child revision

        If necessary, evolve the next changeset. Use --no-evolve to disable this
        behavior.

        Displays the summary line of the destination for clarity.

    options:

     -B --move-bookmark move active bookmark after update
     -m --merge         bring uncommitted change along
        --[no-]evolve   evolve the next changeset if necessary (default: on)
        --no-topic      ignore topic and move topologically
     -n --dry-run       do not perform actions, just print what would be done
        --abort         abort the interrupted next

    (some details hidden, use --verbose to show complete help)

## obslog

    hg obslog [OPTION]... [[-r] REV]...

    aliases: olog

    show the obsolescence history of the specified revisions

        If no revision range is specified, we display the log for the current
        working copy parent.

        By default this command prints the selected revisions and all its
        precursors. For precursors pointing on existing revisions in the
        repository, it will display revisions node id, revision number and the
        first line of the description. For precursors pointing on non existing
        revisions in the repository (that can happen when exchanging obsolescence-
        markers), display only the node id.

        In both case, for each node, its obsolescence marker will be displayed
        with the obsolescence operation (rewritten or pruned) in addition of the
        user and date of the operation.

        The output is a graph by default but can deactivated with the option '--
        no-graph'.

        'o' is a changeset, '@' is a working directory parent, 'x' is obsolete,
        and '+' represents a fork where the changeset from the lines below is a
        parent of the 'o' merge on the same line.

        Paths in the DAG are represented with '|', '/' and so forth.

        Returns 0 on success.

    options ([+] can be repeated):

     -G --[no-]graph        show the revision DAG (default: on)
     -r --rev REV [+]       show the specified revision or revset
     -a --all               show all related changesets, not only precursors
     -p --patch             show the patch between two obs versions
     -f --filternonlocal    filter out non local commits
     -o --[no-]origin       show origin of changesets instead of fate (default:
                            on)
     -T --template TEMPLATE display with template

    (some details hidden, use --verbose to show complete help)

## pdiff

    hg pdiff

    show diff combining committed and uncommitted changes

            This show the combined diff of the current working copy parent commit
            and the uncommitted change in the working copy itself. The diff
            displayed match the content of the commit that a bare 'hg amend' will
            creates.

            See 'hg help diff' for details.

    options ([+] can be repeated):

     -a --text                treat all files as text
     -g --git                 use git extended diff format
        --binary              generate binary diffs in git mode (default)
        --nodates             omit dates from diff headers
        --noprefix            omit a/ and b/ prefixes from filenames
     -p --show-function       show which function each change is in
        --reverse             produce a diff that undoes the changes
     -w --ignore-all-space    ignore white space when comparing lines
     -b --ignore-space-change ignore changes in the amount of white space
     -B --ignore-blank-lines  ignore changes whose lines are all blank
     -Z --ignore-space-at-eol ignore changes in whitespace at EOL
     -U --unified NUM         number of lines of context to show
        --stat                output diffstat-style summary of changes
        --root DIR            produce diffs relative to subdirectory
     -I --include PATTERN [+] include names matching the given patterns
     -X --exclude PATTERN [+] exclude names matching the given patterns
     -S --subrepos            recurse into subrepositories

    (some details hidden, use --verbose to show complete help)

## previous

    hg previous [OPTION]...

    update to parent revision

        Displays the summary line of the destination for clarity.

    options:

     -B --move-bookmark move active bookmark after update
     -m --merge         bring uncommitted change along
        --no-topic      ignore topic and move topologically
     -n --dry-run       do not perform actions, just print what would be done

    (some details hidden, use --verbose to show complete help)

## prune

    hg prune [OPTION]... [-r] REV...

    aliases: obsolete

    mark changesets as obsolete or succeeded by another changeset

        Pruning changesets marks them obsolete, hiding them from the history log,
        provided they have no descendants. Otherwise, all such descendants that
        aren't themselves obsolete become "unstable". Use 'hg evolve' to handle
        this situation.

        When you prune the parent of your working copy, Mercurial updates the
        working copy to a non-obsolete parent.

        You can use "-s/--successor" to tell Mercurial that a newer version
        (successor) of the pruned changeset exists. Mercurial records successor
        revisions in obsolescence markers.

        If you prune a single revision and specify multiple revisions in
        "-s/--successor", you are recording a "split" and must acknowledge it by
        passing "--split". Similarly, when you prune multiple changesets with a
        single successor, you must pass the "--fold" option.

        If you want to supersede multiple revisions at the same time, use the "--
        pair" option to pair the pruned precursor and successor changesets. This
        is commonly useful for resolving history divergence, or when someone else
        edits history without obsolescence enabled.

    options ([+] can be repeated):

     -s --successor REV [+]     successor changeset
     -r --rev REV [+]           revisions to prune
     -k --keep                  does not modify working copy during prune
     -n --note TEXT             store a note on prune
        --pair                  record a pairing, such as a rebase or divergence
                                resolution (pairing multiple precursors to
                                multiple successors)
        --fold                  record a fold (multiple precursors, one successor)
        --split                 record a split (one precursor, multiple
                                successors)
     -B --bookmark BOOKMARK [+] remove revs only reachable from given bookmark
     -d --date DATE             record the specified date in metadata
     -u --user USER             record the specified user in metadata

    (some details hidden, use --verbose to show complete help)

## pstatus

    hg pstatus

    show status combining committed and uncommitted changes

            This show the combined status of the current working copy parent
            commit and the uncommitted change in the working copy itself. The
            status displayed match the content of the commit that a bare 'hg
            amend' will creates.

            See 'hg help status' for details.

    options ([+] can be repeated):

     -A --all                 show status of all files
     -m --modified            show only modified files
     -a --added               show only added files
     -r --removed             show only removed files
     -d --deleted             show only missing files
     -c --clean               show only files without changes
     -u --unknown             show only unknown (not tracked) files
     -i --ignored             show only ignored files
     -n --no-status           hide status prefix
     -C --copies              show source of copied files
     -0 --print0              end filenames with NUL, for use with xargs
     -I --include PATTERN [+] include names matching the given patterns
     -X --exclude PATTERN [+] exclude names matching the given patterns
     -S --subrepos            recurse into subrepositories
     -T --template TEMPLATE   display with template

    (some details hidden, use --verbose to show complete help)

## split

    hg split [OPTION]... [-r REV] [FILE]...

    split a changeset into smaller changesets

        By default, split the current revision by prompting for all its hunks to
        be redistributed into new changesets.

        Use --rev to split a given changeset instead.

        If file patterns are specified only files matching these patterns will be
        considered to be split in earlier changesets. The files that doesn't match
        will be gathered in the last changeset.

    options ([+] can be repeated):

     -i --[no-]interactive use interactive mode (default: on)
     -r --rev REV [+]      revision to split
     -n --note TEXT        store a note on split
     -m --message TEXT     use text as commit message
     -l --logfile FILE     read commit message from file
     -d --date DATE        record the specified date as commit date
     -u --user USER        record the specified user as committer
     -D --current-date     record the current date as commit date
     -U --current-user     record the current user as committer

    (some details hidden, use --verbose to show complete help)

## touch

    hg touch [OPTION]... [-r] REV...

    create successors identical to their predecessors but the changeset ID

        This is used to "resurrect" changesets

    options ([+] can be repeated):

     -r --rev REV [+]     revision to update
     -n --note TEXT       store a note on touch
     -D --duplicate       do not mark the new revision as successor of the old one
     -A --allowdivergence mark the new revision as successor of the old one
                          potentially creating divergence

    (some details hidden, use --verbose to show complete help)

## uncommit

    hg uncommit [OPTION]... [FILE]...

    move changes from parent revision to working directory

        Changes to selected files in the checked out revision appear again as
        uncommitted changed in the working directory. A new revision without the
        selected changes is created, becomes the checked out revision, and
        obsoletes the previous one.

        The --include option specifies patterns to uncommit. The --exclude option
        specifies patterns to keep in the commit.

        The --rev argument let you change the commit file to a content of another
        revision. It still does not change the content of your file in the working
        directory.

        Return 0 if changed files are uncommitted.

    options ([+] can be repeated):

     -a --all                 uncommit all changes when no arguments given
     -r --rev REV             revert commit content to REV instead
        --revert              discard working directory changes after uncommit
     -n --note TEXT           store a note on uncommit
     -I --include PATTERN [+] include names matching the given patterns
     -X --exclude PATTERN [+] exclude names matching the given patterns
     -m --message TEXT        use text as commit message
     -l --logfile FILE        read commit message from file
     -d --date DATE           record the specified date as commit date
     -u --user USER           record the specified user as committer
     -D --current-date        record the current date as commit date
     -U --current-user        record the current user as committer

    (some details hidden, use --verbose to show complete help)