Mercurial > hg
diff mercurial/help/phases.txt @ 15996:0455463655e0 stable
help: add phases topic
author | Matt Mackall <mpm@selenic.com> |
---|---|
date | Thu, 26 Jan 2012 11:23:14 -0600 |
parents | |
children | 916de764b4f6 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mercurial/help/phases.txt Thu Jan 26 11:23:14 2012 -0600 @@ -0,0 +1,61 @@ +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 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] + publishing = False + +See :hg:`help config` for more information on config files. + +.. note:: + Servers running older versions of Mercurial are treated as + publishing. + +See :hg:`help phase` for information on manually manipulating phases.