1 ==============

     2 Topic Tutorial

     3 ==============

     4 

     5 This Mercurial configuration example is used for testing.

     6 

     7 .. Various setup

     8 

     9   $ . "$TESTDIR/testlib/topic_setup.sh"

    10   $ cat >> $HGRCPATH << EOF

    11   > [experimental]

    12   > evolution=all

    13   > [extensions]

    14   > evolve=

    15   > EOF

    16 

    17   $ hg init server

    18 

    19   $ cd server

    20 

    21   $ cat >> .hg/hgrc << EOF

    22   > [ui]

    23   > user= Shopping Master

    24   > EOF

    25 

    26   $ cat >> shopping << EOF

    27   > Spam

    28   > Whizzo butter

    29   > Albatross

    30   > Rat (rather a lot)

    31   > Jugged fish

    32   > Blancmange

    33   > Salmon mousse

    34   > EOF

    35 

    36   $ hg commit -A -m "Shopping list"

    37   adding shopping

    38 

    39   $ cd ..

    40   $ hg clone server client

    41   updating to branch default

    42   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

    43   $ cd client

    44   $ cat >> .hg/hgrc << EOF

    45   > [ui]

    46   > user= Tutorial User

    47   > EOF

    48 #if docgraph-ext

    49   $ . "$TESTDIR/testlib/docgraph_setup.sh" #rest-ignore

    50 #endif

    51 

    52 Topic branches are lightweight branches which disappear when changes are

    53 finalized (moved to the public phase). They can help users to organize and share

    54 their unfinished work.

    55 

    56 In this tutorial, we explain how to use topics for local development. In the first part,

    57 there is a central *publishing* server. Anything pushed to the central server will become public and immutable This means no unfinished work should escapes the local repository.

    58 

    59 

    60 Topic Basics

    61 ============

    62 

    63 Let's say we use Mercurial to manage our shopping list:

    64 

    65   $ hg log --graph

    66   @  changeset:   0:38da43f0a2ea

    67      tag:         tip

    68      user:        test

    69      date:        Thu Jan 01 00:00:00 1970 +0000

    70      summary:     Shopping list

    71   

    72 #if docgraph-ext

    73   $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

    74   .. graphviz::

    75   

    76       strict digraph  {

    77       	graph [rankdir=LR,

    78       		splines=polyline

    79       	];

    80       	node [label="\N"];

    81       	0	 [fillcolor="#9999FF",

    82       		fixedsize=true,

    83       		group=default,

    84       		height=0.5,

    85       		label=0,

    86       		pin=true,

    87       		pos="1,0!",

    88       		shape=circle,

    89       		style=filled,

    90       		width=0.5];

    91       }

    92 #endif

    93 

    94 We are about to make some additions to this list and would like to do them

    95 within a topic. Creating a new topic is done using the ``topic`` command:

    96 

    97   $ hg topics food

    98   marked working directory as topic: food

    99 

   100 Much like a named branch, our topic is active but it does not contain any

   101 changeset yet:

   102 

   103   $ hg topics

   104    * food (0 changesets)

   105 

   106   $ hg summary

   107   parent: 0:38da43f0a2ea tip

   108    Shopping list

   109   branch: default

   110   commit: (clean)

   111   update: (current)

   112   topic:  food

   113 

   114   $ hg log --graph

   115   @  changeset:   0:38da43f0a2ea

   116      tag:         tip

   117      user:        test

   118      date:        Thu Jan 01 00:00:00 1970 +0000

   119      summary:     Shopping list

   120   

   121 

   122 #if docgraph-ext

   123   $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

   124   .. graphviz::

   125   

   126       strict digraph  {

   127       	graph [rankdir=LR,

   128       		splines=polyline

   129       	];

   130       	node [label="\N"];

   131       	0	 [fillcolor="#9999FF",

   132       		fixedsize=true,

   133       		group=default,

   134       		height=0.5,

   135       		label=0,

   136       		pin=true,

   137       		pos="1,0!",

   138       		shape=circle,

   139       		style=filled,

   140       		width=0.5];

   141       }

   142 #endif

   143 

   144 Our next commit will be part of the active topic:

   145 

   146   $ cat >> shopping << EOF

   147   > Egg

   148   > Suggar

   149   > Vinegar

   150   > Oil

   151   > EOF

   152 

   153   $ hg commit -m "adding condiments"

   154   active topic 'food' grew its first changeset

   155 

   156   $ hg log --graph --rev 'topic("food")'

   157   @  changeset:   1:13900241408b

   158   |  tag:         tip

   159   ~  topic:       food

   160      user:        test

   161      date:        Thu Jan 01 00:00:00 1970 +0000

   162      summary:     adding condiments

   163   

   164 

   165 #if docgraph-ext

   166   $ hg docgraph -r "topic("food")" --sphinx-directive --rankdir LR #rest-ignore

   167   .. graphviz::

   168   

   169       strict digraph  {

   170       	graph [rankdir=LR,

   171       		splines=polyline

   172       	];

   173       	node [label="\N"];

   174       	1	 [fillcolor="#9999FF",

   175       		fixedsize=true,

   176       		group=default,

   177       		height=0.5,

   178       		label=1,

   179       		pin=true,

   180       		pos="1,1!",

   181       		shape=pentagon,

   182       		style=filled,

   183       		width=0.5];

   184       }

   185 #endif

   186 

   187 And future commits will be part of that topic too:

   188 

   189   $ cat >> shopping << EOF

   190   > Bananas

   191   > Pear

   192   > Apple

   193   > EOF

   194 

   195   $ hg commit -m "adding fruits"

   196 

   197   $ hg log --graph --rev 'topic("food")'

   198   @  changeset:   2:287de11b401f

   199   |  tag:         tip

   200   |  topic:       food

   201   |  user:        test

   202   |  date:        Thu Jan 01 00:00:00 1970 +0000

   203   |  summary:     adding fruits

   204   |

   205   o  changeset:   1:13900241408b

   206   |  topic:       food

   207   ~  user:        test

   208      date:        Thu Jan 01 00:00:00 1970 +0000

   209      summary:     adding condiments

   210   

   211 

   212 #if docgraph-ext

   213   $ hg docgraph -r "topic("food")" --sphinx-directive --rankdir LR #rest-ignore

   214   .. graphviz::

   215   

   216       strict digraph  {

   217       	graph [rankdir=LR,

   218       		splines=polyline

   219       	];

   220       	node [label="\N"];

   221       	1	 [fillcolor="#9999FF",

   222       		fixedsize=true,

   223       		group=default,

   224       		height=0.5,

   225       		label=1,

   226       		pin=true,

   227       		pos="1,1!",

   228       		shape=pentagon,

   229       		style=filled,

   230       		width=0.5];

   231       	2	 [fillcolor="#9999FF",

   232       		fixedsize=true,

   233       		group=default,

   234       		height=0.5,

   235       		label=2,

   236       		pin=true,

   237       		pos="1,2!",

   238       		shape=pentagon,

   239       		style=filled,

   240       		width=0.5];

   241       	1 -> 2	 [arrowhead=none,

   242       		penwidth=2.0];

   243       }

   244 #endif

   245 

   246 We can get a compact view of the content of our topic using the ``stack``

   247 command:

   248 

   249   $ hg stack

   250   ### topic: food

   251   ### target: default (branch)

   252   t2@ adding fruits (current)

   253   t1: adding condiments

   254   t0^ Shopping list (base)

   255 

   256 The topic deactivates when we update away from it:

   257 

   258   $ hg update default

   259   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   260 

   261   $ hg topics

   262      food (2 changesets)

   263 

   264 Note that ``default`` (name of the branch) now refers to the tipmost

   265 changeset of default without a topic:

   266 

   267   $ hg log --graph

   268   o  changeset:   2:287de11b401f

   269   |  tag:         tip

   270   |  topic:       food

   271   |  user:        test

   272   |  date:        Thu Jan 01 00:00:00 1970 +0000

   273   |  summary:     adding fruits

   274   |

   275   o  changeset:   1:13900241408b

   276   |  topic:       food

   277   |  user:        test

   278   |  date:        Thu Jan 01 00:00:00 1970 +0000

   279   |  summary:     adding condiments

   280   |

   281   @  changeset:   0:38da43f0a2ea

   282      user:        test

   283      date:        Thu Jan 01 00:00:00 1970 +0000

   284      summary:     Shopping list

   285   

   286 

   287 #if docgraph-ext

   288   $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

   289   .. graphviz::

   290   

   291       strict digraph  {

   292       	graph [rankdir=LR,

   293       		splines=polyline

   294       	];

   295       	node [label="\N"];

   296       	0	 [fillcolor="#9999FF",

   297       		fixedsize=true,

   298       		group=default,

   299       		height=0.5,

   300       		label=0,

   301       		pin=true,

   302       		pos="1,0!",

   303       		shape=circle,

   304       		style=filled,

   305       		width=0.5];

   306       	1	 [fillcolor="#9999FF",

   307       		fixedsize=true,

   308       		group=default,

   309       		height=0.5,

   310       		label=1,

   311       		pin=true,

   312       		pos="1,1!",

   313       		shape=pentagon,

   314       		style=filled,

   315       		width=0.5];

   316       	0 -> 1	 [arrowhead=none,

   317       		penwidth=2.0];

   318       	2	 [fillcolor="#9999FF",

   319       		fixedsize=true,

   320       		group=default,

   321       		height=0.5,

   322       		label=2,

   323       		pin=true,

   324       		pos="1,2!",

   325       		shape=pentagon,

   326       		style=filled,

   327       		width=0.5];

   328       	1 -> 2	 [arrowhead=none,

   329       		penwidth=2.0];

   330       }

   331 #endif

   332 And updating back to the topic reactivates it:

   333 

   334   $ hg update food

   335   switching to topic food

   336   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   337 

   338   $ hg topics

   339    * food (2 changesets)

   340 

   341 Updating to any changeset that is part of a topic activates the topic

   342 regardless of how the revision was specified:

   343 

   344   $ hg update default

   345   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   346 

   347   $ hg update --rev 'desc("condiments")'

   348   switching to topic food

   349   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   350 

   351   $ hg topics

   352    * food (2 changesets)

   353 

   354 .. Server side activity:

   355 

   356   $ cd ../server/

   357   $ cat > shopping << EOF

   358   > T-Shirt

   359   > Trousers

   360   > Spam

   361   > Whizzo butter

   362   > Albatross

   363   > Rat (rather a lot)

   364   > Jugged fish

   365   > Blancmange

   366   > Salmon mousse

   367   > EOF

   368 

   369   $ hg commit -A -m "Adding clothes"

   370 

   371   $ cd ../client

   372 

   373 The topic will also affect the rebase and the merge destinations. Let's pull

   374 the latest update from the main server:

   375 

   376   $ hg pull

   377   pulling from $TESTTMP/server (glob)

   378   searching for changes

   379   adding changesets

   380   adding manifests

   381   adding file changes

   382   added 1 changesets with 1 changes to 1 files (+1 heads)

   383   (run 'hg heads' to see heads)

   384 

   385   $ hg log -G

   386   o  changeset:   3:6104862e8b84

   387   |  tag:         tip

   388   |  parent:      0:38da43f0a2ea

   389   |  user:        test

   390   |  date:        Thu Jan 01 00:00:00 1970 +0000

   391   |  summary:     Adding clothes

   392   |

   393   | o  changeset:   2:287de11b401f

   394   | |  topic:       food

   395   | |  user:        test

   396   | |  date:        Thu Jan 01 00:00:00 1970 +0000

   397   | |  summary:     adding fruits

   398   | |

   399   | @  changeset:   1:13900241408b

   400   |/   topic:       food

   401   |    user:        test

   402   |    date:        Thu Jan 01 00:00:00 1970 +0000

   403   |    summary:     adding condiments

   404   |

   405   o  changeset:   0:38da43f0a2ea

   406      user:        test

   407      date:        Thu Jan 01 00:00:00 1970 +0000

   408      summary:     Shopping list

   409   

   410 #if docgraph-ext

   411   $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

   412   .. graphviz::

   413   

   414       strict digraph  {

   415       	graph [rankdir=LR,

   416       		splines=polyline

   417       	];

   418       	node [label="\N"];

   419       	0	 [fillcolor="#9999FF",

   420       		fixedsize=true,

   421       		group=default,

   422       		height=0.5,

   423       		label=0,

   424       		pin=true,

   425       		pos="1,0!",

   426       		shape=circle,

   427       		style=filled,

   428       		width=0.5];

   429       	1	 [fillcolor="#9999FF",

   430       		fixedsize=true,

   431       		group=default,

   432       		height=0.5,

   433       		label=1,

   434       		pin=true,

   435       		pos="1,1!",

   436       		shape=pentagon,

   437       		style=filled,

   438       		width=0.5];

   439       	0 -> 1	 [arrowhead=none,

   440       		penwidth=2.0];

   441       	3	 [fillcolor="#9999FF",

   442       		fixedsize=true,

   443       		group=default,

   444       		height=0.5,

   445       		label=3,

   446       		pin=true,

   447       		pos="1,3!",

   448       		shape=circle,

   449       		style=filled,

   450       		width=0.5];

   451       	0 -> 3	 [arrowhead=none,

   452       		penwidth=2.0];

   453       	2	 [fillcolor="#9999FF",

   454       		fixedsize=true,

   455       		group=default,

   456       		height=0.5,

   457       		label=2,

   458       		pin=true,

   459       		pos="1,2!",

   460       		shape=pentagon,

   461       		style=filled,

   462       		width=0.5];

   463       	1 -> 2	 [arrowhead=none,

   464       		penwidth=2.0];

   465       }

   466 #endif

   467 

   468 The topic head will not be considered when merging from the new head of the

   469 branch:

   470 

   471   $ hg update default

   472   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   473 

   474   $ hg merge

   475   abort: branch 'default' has one head - please merge with an explicit rev

   476   (run 'hg heads' to see all heads)

   477   [255]

   478 

   479 But the topic will see that branch head as a valid destination:

   480 

   481   $ hg update food

   482   switching to topic food

   483   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   484 

   485   $ hg rebase

   486   rebasing 1:13900241408b "adding condiments"

   487   merging shopping

   488   switching to topic food

   489   rebasing 2:287de11b401f "adding fruits"

   490   merging shopping

   491 

   492   $ hg log --graph

   493   @  changeset:   5:2d50db8b5b4c

   494   |  tag:         tip

   495   |  topic:       food

   496   |  user:        test

   497   |  date:        Thu Jan 01 00:00:00 1970 +0000

   498   |  summary:     adding fruits

   499   |

   500   o  changeset:   4:4011b46eeb33

   501   |  topic:       food

   502   |  user:        test

   503   |  date:        Thu Jan 01 00:00:00 1970 +0000

   504   |  summary:     adding condiments

   505   |

   506   o  changeset:   3:6104862e8b84

   507   |  parent:      0:38da43f0a2ea

   508   |  user:        test

   509   |  date:        Thu Jan 01 00:00:00 1970 +0000

   510   |  summary:     Adding clothes

   511   |

   512   o  changeset:   0:38da43f0a2ea

   513      user:        test

   514      date:        Thu Jan 01 00:00:00 1970 +0000

   515      summary:     Shopping list

   516   

   517 #if docgraph-ext

   518   $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

   519   .. graphviz::

   520   

   521       strict digraph  {

   522       	graph [rankdir=LR,

   523       		splines=polyline

   524       	];

   525       	node [label="\N"];

   526       	0	 [fillcolor="#9999FF",

   527       		fixedsize=true,

   528       		group=default,

   529       		height=0.5,

   530       		label=0,

   531       		pin=true,

   532       		pos="1,0!",

   533       		shape=circle,

   534       		style=filled,

   535       		width=0.5];

   536       	3	 [fillcolor="#9999FF",

   537       		fixedsize=true,

   538       		group=default,

   539       		height=0.5,

   540       		label=3,

   541       		pin=true,

   542       		pos="1,3!",

   543       		shape=circle,

   544       		style=filled,

   545       		width=0.5];

   546       	0 -> 3	 [arrowhead=none,

   547       		penwidth=2.0];

   548       	4	 [fillcolor="#9999FF",

   549       		fixedsize=true,

   550       		group=default,

   551       		height=0.5,

   552       		label=4,

   553       		pin=true,

   554       		pos="1,4!",

   555       		shape=pentagon,

   556       		style=filled,

   557       		width=0.5];

   558       	3 -> 4	 [arrowhead=none,

   559       		penwidth=2.0];

   560       	5	 [fillcolor="#9999FF",

   561       		fixedsize=true,

   562       		group=default,

   563       		height=0.5,

   564       		label=5,

   565       		pin=true,

   566       		pos="1,5!",

   567       		shape=pentagon,

   568       		style=filled,

   569       		width=0.5];

   570       	4 -> 5	 [arrowhead=none,

   571       		penwidth=2.0];

   572       }

   573 #endif

   574 

   575 The topic information will disappear when we publish the changesets:

   576 

   577   $ hg topics

   578    * food (2 changesets)

   579 

   580   $ hg push

   581   pushing to $TESTTMP/server (glob)

   582   searching for changes

   583   adding changesets

   584   adding manifests

   585   adding file changes

   586   added 2 changesets with 2 changes to 1 files

   587   2 new obsolescence markers

   588   active topic 'food' is now empty

   589 

   590   $ hg topics

   591    * food (0 changesets)

   592 

   593 The topic still exists, and any new commit will be in the topic. But

   594 note that it is now devoid of any commit.

   595 

   596   $ hg topics --list

   597   ### topic: food

   598   ### target: default (branch)

   599   (stack is empty)

   600   t0^ adding fruits (base current)

   601 

   602   $ hg log --graph

   603   @  changeset:   5:2d50db8b5b4c

   604   |  tag:         tip

   605   |  user:        test

   606   |  date:        Thu Jan 01 00:00:00 1970 +0000

   607   |  summary:     adding fruits

   608   |

   609   o  changeset:   4:4011b46eeb33

   610   |  user:        test

   611   |  date:        Thu Jan 01 00:00:00 1970 +0000

   612   |  summary:     adding condiments

   613   |

   614   o  changeset:   3:6104862e8b84

   615   |  parent:      0:38da43f0a2ea

   616   |  user:        test

   617   |  date:        Thu Jan 01 00:00:00 1970 +0000

   618   |  summary:     Adding clothes

   619   |

   620   o  changeset:   0:38da43f0a2ea

   621      user:        test

   622      date:        Thu Jan 01 00:00:00 1970 +0000

   623      summary:     Shopping list

   624   

   625 #if docgraph-ext

   626   $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

   627   .. graphviz::

   628   

   629       strict digraph  {

   630       	graph [rankdir=LR,

   631       		splines=polyline

   632       	];

   633       	node [label="\N"];

   634       	0	 [fillcolor="#9999FF",

   635       		fixedsize=true,

   636       		group=default,

   637       		height=0.5,

   638       		label=0,

   639       		pin=true,

   640       		pos="1,0!",

   641       		shape=circle,

   642       		style=filled,

   643       		width=0.5];

   644       	3	 [fillcolor="#9999FF",

   645       		fixedsize=true,

   646       		group=default,

   647       		height=0.5,

   648       		label=3,

   649       		pin=true,

   650       		pos="1,3!",

   651       		shape=circle,

   652       		style=filled,

   653       		width=0.5];

   654       	0 -> 3	 [arrowhead=none,

   655       		penwidth=2.0];

   656       	4	 [fillcolor="#9999FF",

   657       		fixedsize=true,

   658       		group=default,

   659       		height=0.5,

   660       		label=4,

   661       		pin=true,

   662       		pos="1,4!",

   663       		shape=circle,

   664       		style=filled,

   665       		width=0.5];

   666       	3 -> 4	 [arrowhead=none,

   667       		penwidth=2.0];

   668       	5	 [fillcolor="#9999FF",

   669       		fixedsize=true,

   670       		group=default,

   671       		height=0.5,

   672       		label=5,

   673       		pin=true,

   674       		pos="1,5!",

   675       		shape=circle,

   676       		style=filled,

   677       		width=0.5];

   678       	4 -> 5	 [arrowhead=none,

   679       		penwidth=2.0];

   680       }

   681 #endif

   682 

   683 If we update to the *default* head, we will leave the topic behind,

   684 and since it is commit-less, it will vanish.

   685 

   686   $ hg update default

   687   clearing empty topic "food"

   688   0 files updated, 0 files merged, 0 files removed, 0 files unresolved

   689 

   690 From there, the topic has been completely forgotten.

   691 

   692   $ hg topics

   693 

   694 

   695 Keep working within topics

   696 ==========================

   697 

   698 Making sure all your new local commit are made within a topic will help your

   699 organise your work. It is possible to ensure this through the Mercurial

   700 configuration.

   701 

   702 For this tutorial, we'll add the config at the repository level:

   703 

   704   $ cat << EOF >> .hg/hgrc

   705   > [experimental]

   706   > topic-mode = enforce

   707   > EOF

   708 

   709 You can also use `hg config --edit` to update your mercurial configuration.

   710 

   711 

   712 Once enforcement is turned on. New local commit will be denied if no topic is active.

   713 

   714   $ echo sickle >> shopping

   715   $ hg commit -m 'Adding sickle'

   716   abort: no active topic

   717   (see 'hg help -e topic.topic-mode' for details)

   718   [255]

   719 

   720 Ok, let's clean this up and delve into multiple topics.

   721 

   722   $ hg revert .

   723   reverting shopping

   724 

   725 

   726 Working with Multiple Topics

   727 ============================

   728 

   729 In the above example, topics do not bring much benefits since you only have one

   730 line of development. Topics start to be more useful when you have to work on

   731 multiple features at the same time.

   732 

   733 We might go shopping in a hardware store in the same go, so let's add some

   734 tools to the shopping list within a new topic:

   735 

   736   $ hg topics tools

   737   marked working directory as topic: tools

   738   $ echo hammer >> shopping

   739   $ hg commit -m 'Adding hammer'

   740   active topic 'tools' grew its first changeset

   741 

   742   $ echo saw >> shopping

   743   $ hg commit -m 'Adding saw'

   744 

   745   $ echo drill >> shopping

   746   $ hg commit -m 'Adding drill'

   747 

   748 But we are not sure we will actually go to the hardware store, so in the

   749 meantime, we want to extend the list with drinks. We go back to the official

   750 default branch and start a new topic:

   751 

   752   $ hg update default

   753   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   754 

   755   $ hg topics drinks

   756   marked working directory as topic: drinks

   757   $ echo 'apple juice' >> shopping

   758   $ hg commit -m 'Adding apple juice'

   759   active topic 'drinks' grew its first changeset

   760 

   761   $ echo 'orange juice' >> shopping

   762   $ hg commit -m 'Adding orange juice'

   763 

   764 We now have two topics:

   765 

   766   $ hg topics

   767    * drinks (2 changesets)

   768      tools  (3 changesets)

   769 

   770 The information displayed by ``hg stack`` adapts to the active topic:

   771 

   772   $ hg stack

   773   ### topic: drinks

   774   ### target: default (branch)

   775   t2@ Adding orange juice (current)

   776   t1: Adding apple juice

   777   t0^ adding fruits (base)

   778 

   779   $ hg update tools

   780   switching to topic tools

   781   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   782 

   783   $ hg stack

   784   ### topic: tools

   785   ### target: default (branch)

   786   t3@ Adding drill (current)

   787   t2: Adding saw

   788   t1: Adding hammer

   789   t0^ adding fruits (base)

   790 

   791 They are seen as independent branches by Mercurial. No rebase or merge

   792 between them will be attempted by default:

   793 

   794   $ hg rebase

   795   nothing to rebase

   796   [1]

   797 

   798 We simulate independant contributions to the repo with this

   799 activity:

   800 

   801   $ cd ../server

   802   $ hg update

   803   1 files updated, 0 files merged, 0 files removed, 0 files unresolved

   804   $ mv shopping foo

   805   $ echo 'Coat' > shopping

   806   $ cat foo >> shopping

   807   $ hg commit -m 'add a coat'

   808   $ echo 'Coat' > shopping

   809   $ echo 'Shoes' >> shopping

   810   $ cat foo >> shopping

   811   $ rm foo

   812   $ hg commit -m 'add a pair of shoes'

   813   $ cd ../client

   814 

   815 Let's discover what other people did contribute:

   816 

   817   $ hg pull

   818   pulling from $TESTTMP/server (glob)

   819   searching for changes

   820   adding changesets

   821   adding manifests

   822   adding file changes

   823   added 2 changesets with 2 changes to 1 files (+1 heads)

   824   (run 'hg heads' to see heads)

   825 

   826 There are new changes! We can simply use ``hg rebase`` to update our

   827 changeset on top of the latest:

   828 

   829   $ hg log -G

   830   o  changeset:   12:fbff9bc37a43

   831   |  tag:         tip

   832   |  user:        test

   833   |  date:        Thu Jan 01 00:00:00 1970 +0000

   834   |  summary:     add a pair of shoes

   835   |

   836   o  changeset:   11:f2d6cacc6115

   837   |  parent:      5:2d50db8b5b4c

   838   |  user:        test

   839   |  date:        Thu Jan 01 00:00:00 1970 +0000

   840   |  summary:     add a coat

   841   |

   842   | o  changeset:   10:70dfa201ed73

   843   | |  topic:       drinks

   844   | |  user:        test

   845   | |  date:        Thu Jan 01 00:00:00 1970 +0000

   846   | |  summary:     Adding orange juice

   847   | |

   848   | o  changeset:   9:8dfa45bd5e0c

   849   |/   topic:       drinks

   850   |    parent:      5:2d50db8b5b4c

   851   |    user:        test

   852   |    date:        Thu Jan 01 00:00:00 1970 +0000

   853   |    summary:     Adding apple juice

   854   |

   855   | @  changeset:   8:34255b455dac

   856   | |  topic:       tools

   857   | |  user:        test

   858   | |  date:        Thu Jan 01 00:00:00 1970 +0000

   859   | |  summary:     Adding drill

   860   | |

   861   | o  changeset:   7:cffff85af537

   862   | |  topic:       tools

   863   | |  user:        test

   864   | |  date:        Thu Jan 01 00:00:00 1970 +0000

   865   | |  summary:     Adding saw

   866   | |

   867   | o  changeset:   6:183984ef46d1

   868   |/   topic:       tools

   869   |    user:        test

   870   |    date:        Thu Jan 01 00:00:00 1970 +0000

   871   |    summary:     Adding hammer

   872   |

   873   o  changeset:   5:2d50db8b5b4c

   874   |  user:        test

   875   |  date:        Thu Jan 01 00:00:00 1970 +0000

   876   |  summary:     adding fruits

   877   |

   878   o  changeset:   4:4011b46eeb33

   879   |  user:        test

   880   |  date:        Thu Jan 01 00:00:00 1970 +0000

   881   |  summary:     adding condiments

   882   |

   883   o  changeset:   3:6104862e8b84

   884   |  parent:      0:38da43f0a2ea

   885   |  user:        test

   886   |  date:        Thu Jan 01 00:00:00 1970 +0000

   887   |  summary:     Adding clothes

   888   |

   889   o  changeset:   0:38da43f0a2ea

   890      user:        test

   891      date:        Thu Jan 01 00:00:00 1970 +0000

   892      summary:     Shopping list

   893   

   894 #if docgraph-ext

   895   $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

   896   .. graphviz::

   897   

   898       strict digraph  {

   899       	graph [rankdir=LR,

   900       		splines=polyline

   901       	];

   902       	node [label="\N"];

   903       	0	 [fillcolor="#9999FF",

   904       		fixedsize=true,

   905       		group=default,

   906       		height=0.5,

   907       		label=0,

   908       		pin=true,

   909       		pos="1,0!",

   910       		shape=circle,

   911       		style=filled,

   912       		width=0.5];

   913       	3	 [fillcolor="#9999FF",

   914       		fixedsize=true,

   915       		group=default,

   916       		height=0.5,

   917       		label=3,

   918       		pin=true,

   919       		pos="1,3!",

   920       		shape=circle,

   921       		style=filled,

   922       		width=0.5];

   923       	0 -> 3	 [arrowhead=none,

   924       		penwidth=2.0];

   925       	4	 [fillcolor="#9999FF",

   926       		fixedsize=true,

   927       		group=default,

   928       		height=0.5,

   929       		label=4,

   930       		pin=true,

   931       		pos="1,4!",

   932       		shape=circle,

   933       		style=filled,

   934       		width=0.5];

   935       	3 -> 4	 [arrowhead=none,

   936       		penwidth=2.0];

   937       	5	 [fillcolor="#9999FF",

   938       		fixedsize=true,

   939       		group=default,

   940       		height=0.5,

   941       		label=5,

   942       		pin=true,

   943       		pos="1,5!",

   944       		shape=circle,

   945       		style=filled,

   946       		width=0.5];

   947       	4 -> 5	 [arrowhead=none,

   948       		penwidth=2.0];

   949       	6	 [fillcolor="#9999FF",

   950       		fixedsize=true,

   951       		group=default,

   952       		height=0.5,

   953       		label=6,

   954       		pin=true,

   955       		pos="1,6!",

   956       		shape=pentagon,

   957       		style=filled,

   958       		width=0.5];

   959       	5 -> 6	 [arrowhead=none,

   960       		penwidth=2.0];

   961       	9	 [fillcolor="#9999FF",

   962       		fixedsize=true,

   963       		group=default,

   964       		height=0.5,

   965       		label=9,

   966       		pin=true,

   967       		pos="1,9!",

   968       		shape=pentagon,

   969       		style=filled,

   970       		width=0.5];

   971       	5 -> 9	 [arrowhead=none,

   972       		penwidth=2.0];

   973       	11	 [fillcolor="#9999FF",

   974       		fixedsize=true,

   975       		group=default,

   976       		height=0.5,

   977       		label=11,

   978       		pin=true,

   979       		pos="1,11!",

   980       		shape=circle,

   981       		style=filled,

   982       		width=0.5];

   983       	5 -> 11	 [arrowhead=none,

   984       		penwidth=2.0];

   985       	7	 [fillcolor="#9999FF",

   986       		fixedsize=true,

   987       		group=default,

   988       		height=0.5,

   989       		label=7,

   990       		pin=true,

   991       		pos="1,7!",

   992       		shape=pentagon,

   993       		style=filled,

   994       		width=0.5];

   995       	6 -> 7	 [arrowhead=none,

   996       		penwidth=2.0];

   997       	8	 [fillcolor="#9999FF",

   998       		fixedsize=true,

   999       		group=default,

  1000       		height=0.5,

  1001       		label=8,

  1002       		pin=true,

  1003       		pos="1,8!",

  1004       		shape=pentagon,

  1005       		style=filled,

  1006       		width=0.5];

  1007       	7 -> 8	 [arrowhead=none,

  1008       		penwidth=2.0];

  1009       	10	 [fillcolor="#9999FF",

  1010       		fixedsize=true,

  1011       		group=default,

  1012       		height=0.5,

  1013       		label=10,

  1014       		pin=true,

  1015       		pos="1,10!",

  1016       		shape=pentagon,

  1017       		style=filled,

  1018       		width=0.5];

  1019       	9 -> 10	 [arrowhead=none,

  1020       		penwidth=2.0];

  1021       	12	 [fillcolor="#9999FF",

  1022       		fixedsize=true,

  1023       		group=default,

  1024       		height=0.5,

  1025       		label=12,

  1026       		pin=true,

  1027       		pos="1,12!",

  1028       		shape=circle,

  1029       		style=filled,

  1030       		width=0.5];

  1031       	11 -> 12	 [arrowhead=none,

  1032       		penwidth=2.0];

  1033       }

  1034 #endif

  1035 

  1036   $ hg rebase

  1037   rebasing 6:183984ef46d1 "Adding hammer"

  1038   merging shopping

  1039   switching to topic tools

  1040   rebasing 7:cffff85af537 "Adding saw"

  1041   merging shopping

  1042   rebasing 8:34255b455dac "Adding drill"

  1043   merging shopping

  1044 

  1045 But what about the other topic? You can use 'hg topics --verbose' to see

  1046 information about all the topics:

  1047 

  1048   $ hg topics --verbose

  1049      drinks (on branch: default, 2 changesets, 2 behind)

  1050    * tools  (on branch: default, 3 changesets)

  1051 

  1052 The "2 behind" is telling you that there are 2 new changesets over the base of the topic.

  1053 

  1054 Pushing that topic would create a new head, and therefore will be prevented:

  1055 

  1056   $ hg push --rev drinks

  1057   pushing to $TESTTMP/server (glob)

  1058   searching for changes

  1059   abort: push creates new remote head 70dfa201ed73!

  1060   (merge or see 'hg help push' for details about pushing new heads)

  1061   [255]

  1062 

  1063 

  1064 Even after a rebase, pushing all active topics at the same time would publish

  1065 them to the default branch, and then mercurial would complain about the

  1066 multiple *public* heads it would create on that branch:

  1067 

  1068   $ hg rebase -b drinks

  1069   rebasing 9:8dfa45bd5e0c "Adding apple juice"

  1070   merging shopping

  1071   switching to topic drinks

  1072   rebasing 10:70dfa201ed73 "Adding orange juice"

  1073   merging shopping

  1074   switching to topic tools

  1075 

  1076   $ hg push

  1077   pushing to $TESTTMP/server (glob)

  1078   searching for changes

  1079   abort: push creates new remote head 4cd7c1591a67!

  1080   (merge or see 'hg help push' for details about pushing new heads)

  1081   [255]

  1082 

  1083 Publishing only one of them is allowed (as long as it does not create a new

  1084 branch head as we just saw in the previous case):

  1085 

  1086   $ hg push -r drinks

  1087   pushing to $TESTTMP/server (glob)

  1088   searching for changes

  1089   adding changesets

  1090   adding manifests

  1091   adding file changes

  1092   added 2 changesets with 2 changes to 1 files

  1093   2 new obsolescence markers

  1094 

  1095 The published topic has now disappeared, and the other is now marked as

  1096 "behind":

  1097 

  1098   $ hg topics --verbose

  1099    * tools (on branch: default, 3 changesets, 2 behind)

  1100 

  1101   $ hg stack

  1102   ### topic: tools

  1103   ### target: default (branch), 2 behind

  1104   t3@ Adding drill (current)

  1105   t2: Adding saw

  1106   t1: Adding hammer

  1107   t0^ add a pair of shoes (base)

  1108 

  1109 Working Within Your Stack

  1110 ===========================

  1111 

  1112 Navigating within your stack

  1113 ----------------------------

  1114 

  1115 As we saw before `stack` displays changesets on your current topic in a clean way:

  1116 

  1117   $ hg topics --verbose

  1118    * tools (on branch: default, 3 changesets, 2 behind)

  1119 

  1120   $ hg stack

  1121   ### topic: tools

  1122   ### target: default (branch), 2 behind

  1123   t3@ Adding drill (current)

  1124   t2: Adding saw

  1125   t1: Adding hammer

  1126   t0^ add a pair of shoes (base)

  1127 

  1128 You can navigate in your current stack with `previous` and `next`.

  1129 

  1130 `previous` will bring you back to the parent of the topic head.

  1131 

  1132   $ hg previous

  1133   1 files updated, 0 files merged, 0 files removed, 0 files unresolved