15   $ hg help -e topic

    16   topic extension - support for topic branches

    17   

    18   Topic branches are lightweight branches which disappear when changes are

    19   finalized (move to the public phase).

    20   

    21   Compared to bookmark, topic is reference carried by each changesets of the

    22   series instead of just the single head revision.  Topic are quite similar to

    23   the way named branch work, except they eventually fade away when the changeset

    24   becomes part of the immutable history. Changeset can belong to both a topic

    25   and a named branch, but as long as it is mutable, its topic identity will

    26   prevail. As a result, default destination for 'update', 'merge', etc...  will

    27   take topic into account. When a topic is active these operations will only

    28   consider other changesets on that topic (and, in some occurrence, bare

    29   changeset on same branch).  When no topic is active, changeset with topic will

    30   be ignored and only bare one on the same branch will be taken in account.

    31   

    32   There is currently two commands to be used with that extension: 'topics' and

    33   'stack'.

    34   

    35   The 'hg topics' command is used to set the current topic, change and list

    36   existing one. 'hg topics --verbose' will list various information related to

    37   each topic.

    38   

    39   The 'stack' will show you information about the stack of commit belonging to

    40   your current topic.

    41   

    42   Topic is offering you aliases reference to changeset in your current topic

    43   stack as 't#'. For example, 't1' refers to the root of your stack, 't2' to the

    44   second commits, etc. The 'hg stack' command show these number.

    45   

    46   Push behavior will change a bit with topic. When pushing to a publishing

    47   repository the changesets will turn public and the topic data on them will

    48   fade away. The logic regarding pushing new heads will behave has before,

    49   ignore any topic related data. When pushing to a non-publishing repository

    50   (supporting topic), the head checking will be done taking topic data into

    51   account. Push will complain about multiple heads on a branch if you push

    52   multiple heads with no topic information on them (or multiple public heads).

    53   But pushing a new topic will not requires any specific flag. However, pushing

    54   multiple heads on a topic will be met with the usual warning.

    55   

    56   The 'evolve' extension takes 'topic' into account. 'hg evolve --all' will

    57   evolve all changesets in the active topic. In addition, by default. 'hg next'

    58   and 'hg prev' will stick to the current topic.

    59   

    60   Be aware that this extension is still an experiment, commands and other

    61   features are likely to be change/adjusted/dropped over time as we refine the

    62   concept.

    63   

    64   topic-mode

    65   ==========

    66   

    67   The topic extension can be configured to ensure the user do not forget to add

    68   a topic when committing a new topic:

    69   

    70     [experimental]

    71     # behavior when commit is made without an active topic

    72     topic-mode = ignore # do nothing special (default)

    73     topic-mode = warning # print a warning

    74     topic-mode = enforce # abort the commit (except for merge)

    75     topic-mode = enforce-all # abort the commit (even for merge)

    76     topic-mode = random # use a randomized generated topic (except for merge)

    77     topic-mode = random-all # use a randomized generated topic (even for merge)

    78   

    79   Single head enforcing

    80   =====================

    81   

    82   The extensions come with an option to enforce that there is only one heads for

    83   each name in the repository at any time.

    84   

    85       [experimental] enforce-single-head = yes

    86   

    87   Publishing behavior

    88   ===================

    89   

    90   Topic vanish when changeset move to the public phases. Moving to the public

    91   phase usually happens on push, but it is possible to update that behavior. The

    92   server needs to have specific config for this.

    93   

    94       # everything pushed become public (the default) [phase] publish = yes

    95   

    96       # nothing push turned public [phase] publish = no

    97   

    98       # topic branches are not published, changeset without topic are [phase]

    99       publish = no [experimental] topic.publish-bare-branch = yes

   100   

   101   In addition, the topic extension adds a "--publish" flag on 'hg push'. When

   102   used, the pushed revisions are published if the push succeeds. It also applies

   103   to common revisions selected by the push.

   104   

   105   list of commands:

   106   

   107    stack         list all changesets in a topic and other information

   108    topics        View current topic, set current topic, change topic for a set

   109                  of revisions, or see all topics.

   110   

   111   (use 'hg help -v topic' to show built-in aliases and global options)