26 States Extension

    26 See each extension documentation for details

    27 ================

    28 

    29 state: experimentally functional

    30 

    31 (see http://mercurial.selenic.com/wiki/StatesPlan)

    32 

    33 This extension adds the state concept. A changeset now has one of the following

    34 *states*:

    35 

    36 :published:

    37 

    38     Changesets in the ``published`` state are the core of the history.  They are

    39     changesets that you published to the world. People can expect them to always

    40     exist. They are changesets as you know them. **By default all changesets

    41     are published**

    42 

    43     * They are exchanged with other repositories (included in pull//push).

    44 

    45     * They are not mutable, extensions rewriting history should refuse to

    46       rewrite them.

    47 

    48 :ready:

    49 

    50     Changesets in the ``ready`` state have not yet been accepted in the

    51     immutable history. You can share them with others for review, testing or

    52     improvement. Any ``ready`` changeset can either be included in the

    53     published history (and become immutable) or be rewritten and never make it

    54     to the published history.

    55 

    56     * They are exchanged with other repositories (included in pull//push).

    57     * They are mutable, extensions rewriting history accept to work on them.

    58 

    59 :draft:

    60 

    61     Changesets in the ``draft`` state are heavy work in progress you are not

    62     yet willing to share with others.

    63 

    64     * They are not exchanged with other repositories. pull//push do not see them.

    65     * They are mutable, extensions rewriting history accept to work on them.

    66 

    67 

    68 States of changesets have to be consistent with each other. A ``published``

    69 changeset can only have ``published`` ancestors. A ``ready`` changeset can only

    70 have ``published`` or ``ready`` ancestors.

    71 

    72 

    73 Usage and Feature

    74 ------------------

    75 

    76 By default all changesets in the repository are ``published``. Other states must

    77 be explicitly activated. When a state is not activated, changesets in this state

    78 are handled as changesets of the state before it (``draft`` are handled as

    79 ``ready``, ``ready`` are handled as ``published``).

    80 

    81 Changesets will automatically move to ``published`` state when:

    82 

    83 * pushed to a repo that doesn't support the ``ready`` state.

    84 

    85 * Tagged by a non local tag.

    86 

    87 Commands

    88 ........

    89 

    90 The extension adds a ``hg states`` command to choose which states are used by a

    91 repository, see ``hg help states for details``.

    92 

    93 A command is also added for each active state. The command has the name of the

    94 state and is used to manually change the state of a changeset. This is mainly

    95 useful to move changesets from ``draft`` to ``ready``.:: 

    96 

    97     hg ready tip

    98 

    99 Template

   100 ........

   101 

   102 A new template keyword ``{state}`` has been added.

   103 

   104 Revset

   105 ........

   106 

   107 We add new ``readyheads()`` and ``publishedheads()`` revset directives. This

   108 returns the heads of each state **as if all of them were activated**.

   109 

   110 FAQ

   111 ---

   112 

   113 Why to you store activate state outside ``.hg/hgrc``?

   114 .....................................................

   115 

   116 ``.hg/hgrc`` might be ignored for trust reason. We don't want the trust issue

   117 to interfer with enabled state information.

   118 

   119 Why is the ``dead`` state missing?

   120 .....................................................

   121 

   122 1. The ``dead`` state has a different behaviour that requires more work to be

   123 implemented.

   124 

   125 2. I believe that the use cases of ``dead changeset`` are better covered by the

   126 ``obsolete`` extension.

   127 

   128 To Do

   129 -----

   130 

   131 * be robust to unknown changeset in boundary

   132 

   133 * Moving boundary backward (code exists in the ``liquid`` extension done at the

   134   CPH sprint)

   135 

   136 * support for default value in configuration (for init and clone)

   137 

   138 * stronger pull//push support (unknown remote heads confuse the current code)

   139 

   140 * display the number of changesets that change state when activating a state.

   141 

   142 * have a switch to select if changesets do change state on state activation.

   143 

   144 * proper revset directive.

   145 

   146     - for changeset in states

   147     - for "in use" changeset heads.

   148