comparison tests/test-topic-tutorial.t @ 2885:e61a9fde2125

topic: tutorial grammar fixes

2884:5a836fa589a4

  > [ui]
  > user= Tutorial User
  > EOF

Topic branches are lightweight branches which disappear when changes are
finalized (move to the public phase). They can help users to organize and share
their unfinished work.

Topic Basics
============

     user:        test
     date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     Shopping list
  

We are about to make some additions to this list and would like to do them 
within a topic. Creating a new topic is done using the ``topic`` command:

  $ hg topic food

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

  $ hg topic
   * food

  $ hg summary

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

Working with Multiple Topics
============================

In the above example, topics do not bring much benefit since you only have one
line of development. Topics start to be more useful when you have to work on
multiple features at the same time.

We might go shopping in a hardware store in the same go, so let's add some
tools to the shopping list within a new topic:

===========================

Navigating within your stack
----------------------------

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

  $ hg topics --verbose
   * tools (on branch: default, 3 changesets, 2 behind)

  $ hg stack

  o  changeset:   12:fbff9bc37a43
  |  user:        test
  ~  date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     add a pair of shoes
  
Fortunately stack show you a better visualization:

  $ hg stack
  ### topic: tools
  ### branch: default, 2 behind
  t3$ Adding drill (unstable)

  t1^ Adding hammer to the shopping list (base)
  t2@ Adding nails (current)
  t1: Adding hammer to the shopping list
  t0^ add a pair of shoes (base)

Solving this situation is easy with a topic, use merge or rebase.
Merge within a multi-headed stack will use the other topic head as
redestination if the topic has multiple heads.

  $ hg log -G
  @  changeset:   21:f936c6da9d61

  t3: Adding saw
  t2: Adding nails
  t1: Adding hammer to the shopping list
  t0^ add a pair of shoes (base)

Collaborating through non-publishing server
===========================================

.. setup:

.. Let's create a non-publishing server:

  updating to branch default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ cd client

We can now share theses drafts changesets:

  $ hg push ../non-publishing-server -r tools
  pushing to ../non-publishing-server
  searching for changes
  adding changesets
  adding manifests
  adding file changes
  added 4 changesets with 4 changes to 1 files (+1 heads)
  8 new obsolescence markers

Pushing the new topic branch to a non publishing server did not required
--force. As long as new heads are on their own topic, Mercurial will not
complains about them.

From another client, we will gets them with their topic:

  $ cd ../other-client

  $ hg pull ../non-publishing-server
  pulling from ../non-publishing-server

2885:e61a9fde2125

  > [ui]
  > user= Tutorial User
  > EOF

Topic branches are lightweight branches which disappear when changes are
finalized (moved to the public phase). They can help users to organize and share
their unfinished work.

Topic Basics
============

     user:        test
     date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     Shopping list
  

We are about to make some additions to this list and would like to do them
within a topic. Creating a new topic is done using the ``topic`` command:

  $ hg topic food

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

  $ hg topic
   * food

  $ hg summary

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

Working with Multiple Topics
============================

In the above example, topics do not bring much benefits since you only have one
line of development. Topics start to be more useful when you have to work on
multiple features at the same time.

We might go shopping in a hardware store in the same go, so let's add some
tools to the shopping list within a new topic:

===========================

Navigating within your stack
----------------------------

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

  $ hg topics --verbose
   * tools (on branch: default, 3 changesets, 2 behind)

  $ hg stack

  o  changeset:   12:fbff9bc37a43
  |  user:        test
  ~  date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     add a pair of shoes
  
Fortunately stack shows you a better visualization:

  $ hg stack
  ### topic: tools
  ### branch: default, 2 behind
  t3$ Adding drill (unstable)

  t1^ Adding hammer to the shopping list (base)
  t2@ Adding nails (current)
  t1: Adding hammer to the shopping list
  t0^ add a pair of shoes (base)

Solving this situation is easy with a topic: use merge or rebase.
Merge within a multi-headed stack will use the other topic head as
redestination if the topic has multiple heads.

  $ hg log -G
  @  changeset:   21:f936c6da9d61

  t3: Adding saw
  t2: Adding nails
  t1: Adding hammer to the shopping list
  t0^ add a pair of shoes (base)

Collaborating through a non-publishing server
========================--===================

.. setup:

.. Let's create a non-publishing server:

  updating to branch default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ cd client

We can now share these draft changesets:

  $ hg push ../non-publishing-server -r tools
  pushing to ../non-publishing-server
  searching for changes
  adding changesets
  adding manifests
  adding file changes
  added 4 changesets with 4 changes to 1 files (+1 heads)
  8 new obsolescence markers

Pushing the new topic branch to a non publishing server did not require
--force. As long as new heads are on their own topic, Mercurial will not
complain about them.

From another client, we will get them with their topic:

  $ cd ../other-client

  $ hg pull ../non-publishing-server
  pulling from ../non-publishing-server