docs/Development-Case

Help: phases

Working with Phases

    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.