--- a/mercurial/help.py Thu Jan 26 12:09:14 2012 -0200
+++ b/mercurial/help.py Thu Jan 26 11:23:14 2012 -0600
@@ -73,6 +73,7 @@
(["glossary"], _("Glossary"), loaddoc('glossary')),
(["hgignore", "ignore"], _("syntax for Mercurial ignore files"),
loaddoc('hgignore')),
+ (["phases"], _("Working with Phases"), loaddoc('phases')),
])
# Map topics to lists of callable taking the current topic help and
--- /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.
--- a/tests/test-globalopts.t Thu Jan 26 12:09:14 2012 -0200
+++ b/tests/test-globalopts.t Thu Jan 26 11:23:14 2012 -0600
@@ -347,6 +347,7 @@
merge-tools Merge Tools
multirevs Specifying Multiple Revisions
patterns File Name Patterns
+ phases Working with Phases
revisions Specifying Single Revisions
revsets Specifying Revision Sets
subrepos Subrepositories
@@ -430,6 +431,7 @@
merge-tools Merge Tools
multirevs Specifying Multiple Revisions
patterns File Name Patterns
+ phases Working with Phases
revisions Specifying Single Revisions
revsets Specifying Revision Sets
subrepos Subrepositories
--- a/tests/test-help.t Thu Jan 26 12:09:14 2012 -0200
+++ b/tests/test-help.t Thu Jan 26 11:23:14 2012 -0600
@@ -119,6 +119,7 @@
merge-tools Merge Tools
multirevs Specifying Multiple Revisions
patterns File Name Patterns
+ phases Working with Phases
revisions Specifying Single Revisions
revsets Specifying Revision Sets
subrepos Subrepositories
@@ -196,6 +197,7 @@
merge-tools Merge Tools
multirevs Specifying Multiple Revisions
patterns File Name Patterns
+ phases Working with Phases
revisions Specifying Single Revisions
revsets Specifying Revision Sets
subrepos Subrepositories
@@ -691,6 +693,7 @@
merge-tools Merge Tools
multirevs Specifying Multiple Revisions
patterns File Name Patterns
+ phases Working with Phases
revisions Specifying Single Revisions
revsets Specifying Revision Sets
subrepos Subrepositories