diff mercurial/help/phases.txt @ 15996:0455463655e0 stable

help: add phases topic

--- /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.