What are phases?
Phases are a system for tracking which changesets have been or
should be shared. This helps prevent common mistakes when
modifying history (for instance, with the mq or rebase
extensions).
Each changeset in a repository is in one of the following phases:
• public : changeset is visible on a public server
• draft : changeset is not yet published
• secret : changeset should not be pushed, pulled, or cloned
These phases are ordered (public < draft < secret) and no
changeset can be in a lower phase than its ancestors. For
instance, if a changeset is public, all its ancestors are also
public. Lastly, changeset phases should only be changed towards
the public phase.
How are phases managed?
For the most part, phases should work transparently. By default,
a changeset is created in the draft phase and is moved into the
public phase when it is pushed to another repository.
Once changesets become public, extensions like mq and rebase will
refuse to operate on them to prevent creating duplicate
changesets. Phases can also be manually manipulated with the hg
phase command if needed. See hg help -v phase for examples.
Phases and servers
Normally, all servers are publishing by default. This means:
- all draft changesets that are pulled or cloned appear in phase
public on the client
- all draft changesets that are pushed appear as public on both
client and server
- secret changesets are neither pushed, pulled, or cloned
Note Pulling a draft changeset from a publishing server does
not mark it as public on the server side due to the
read-only nature of pull.
Sometimes it may be desirable to push and pull changesets in the
draft phase to share unfinished work. This can be done by setting
a repository to disable publishing in its configuration file:
[phases]
publish = False
See hg help config for more information on config files.
Note Servers running older versions of Mercurial are treated as
publishing.
Examples
• list changesets in draft or secret phase:
hg log -r "not public()"
• change all secret changesets to draft:
hg phase --draft "secret()"
• forcibly move the current changeset and descendants from
public to draft:
hg phase --force --draft .
• show a list of changeset revision and phase:
hg log --template "{rev} {phase}\n"
• resynchronize draft changesets relative to a remote
repository:
hg phase -fd 'outgoing(URL)'
See hg help phase for more information on manually manipulating
phases.
