Mercurial > hg
annotate mercurial/help/phases.txt @ 17267:979b107eaea2 stable
doc: unify section level between help topics
Some help topics use "-" for the top level underlining section mark,
but "-" is used also for the top level categorization in generated
documents: "hg.1.html", for example.
So, TOC in such documents contain "sections in each topics", too.
This patch changes underlining section mark in some help topics to
unify section level in generated documents.
After this patching, levels of each section marks are:
level0
""""""
level1
======
level2
------
level3
......
level4
######
And use of section markers in each documents are:
- mercurial/help/*.txt can use level1 or more
(now these use level1 and level2)
- help for core commands can use level2 or more
(now these use no section marker)
- descriptions of extensions can use level2 or more
(now hgext/acl uses level2)
- help for commands defined in extension can use level4 or more
(now "convert" of hgext/convert uses level4)
"Level0" is used as top level categorization only in "doc/hg.1.txt"
and the intermediate file generated by "doc/gendoc.py", so end users
don't see it in "hg help" outoput and so on.
author | FUJIWARA Katsunori <foozy@lares.dti.ne.jp> |
---|---|
date | Wed, 25 Jul 2012 16:40:38 +0900 |
parents | 3d26d69ef822 |
children | 170fc0949fb6 |
rev | line source |
---|---|
15996 | 1 What are phases? |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16244
diff
changeset
|
2 ================ |
15996 | 3 |
4 Phases are a system for tracking which changesets have been or should | |
5 be shared. This helps prevent common mistakes when modifying history | |
6 (for instance, with the mq or rebase extensions). | |
7 | |
8 Each changeset in a repository is in one of the following phases: | |
9 | |
10 - public : changeset is visible on a public server | |
11 - draft : changeset is not yet published | |
12 - secret : changeset should not be pushed, pulled, or cloned | |
13 | |
14 These phases are ordered (public < draft < secret) and no changeset | |
15 can be in a lower phase than its ancestors. For instance, if a | |
16 changeset is public, all its ancestors are also public. Lastly, | |
16244
3d26d69ef822
help: add verb to sentence in phases.txt
Johan Samyn <johan.samyn@gmail.com>
parents:
16041
diff
changeset
|
17 changeset phases should only be changed towards the public phase. |
15996 | 18 |
19 How are phases managed? | |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16244
diff
changeset
|
20 ======================= |
15996 | 21 |
22 For the most part, phases should work transparently. By default, a | |
23 changeset is created in the draft phase and is moved into the public | |
24 phase when it is pushed to another repository. | |
25 | |
26 Once changesets become public, extensions like mq and rebase will | |
27 refuse to operate on them to prevent creating duplicate changesets. | |
28 Phases can also be manually manipulated with the :hg:`phase` command | |
29 if needed. See :hg:`help -v phase` for examples. | |
30 | |
31 Phases and servers | |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16244
diff
changeset
|
32 ================== |
15996 | 33 |
34 Normally, all servers are ``publishing`` by default. This means:: | |
35 | |
36 - all draft changesets that are pulled or cloned appear in phase | |
37 public on the client | |
38 | |
39 - all draft changesets that are pushed appear as public on both | |
40 client and server | |
41 | |
42 - secret changesets are neither pushed, pulled, or cloned | |
43 | |
44 .. note:: | |
45 Pulling a draft changeset from a publishing server does not mark it | |
46 as public on the server side due to the read-only nature of pull. | |
47 | |
48 Sometimes it may be desirable to push and pull changesets in the draft | |
49 phase to share unfinished work. This can be done by setting a | |
50 repository to disable publishing in its configuration file:: | |
51 | |
52 [phases] | |
16000
25fa240139cb
help: fix publish option spelling in phases topic
Matt Mackall <mpm@selenic.com>
parents:
15998
diff
changeset
|
53 publish = False |
15998
916de764b4f6
help/phases: remove trailing whitespace
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
15996
diff
changeset
|
54 |
15996 | 55 See :hg:`help config` for more information on config files. |
56 | |
57 .. note:: | |
58 Servers running older versions of Mercurial are treated as | |
59 publishing. | |
60 | |
16011
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
61 Examples |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16244
diff
changeset
|
62 ======== |
16011
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
63 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
64 - list changesets in draft or secret phase:: |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
65 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
66 hg log -r "not public()" |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
67 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
68 - change all secret changesets to draft:: |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
69 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
70 hg phase --draft "secret()" |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
71 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
72 - forcibly move the current changeset and descendants from public to draft:: |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
73 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
74 hg phase --force --draft . |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
75 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
76 - show a list of changeset revision and phase:: |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
77 |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
78 hg log --template "{rev} {phase}\n" |
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
79 |
16041
6a959318c58e
phases: add resync example to help topic
Matt Mackall <mpm@selenic.com>
parents:
16011
diff
changeset
|
80 - resynchronize draft changesets relative to a remote repository:: |
6a959318c58e
phases: add resync example to help topic
Matt Mackall <mpm@selenic.com>
parents:
16011
diff
changeset
|
81 |
6a959318c58e
phases: add resync example to help topic
Matt Mackall <mpm@selenic.com>
parents:
16011
diff
changeset
|
82 hg phase -fd 'outgoing(URL)' |
6a959318c58e
phases: add resync example to help topic
Matt Mackall <mpm@selenic.com>
parents:
16011
diff
changeset
|
83 |
16011
f2c49d9dee57
help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents:
16000
diff
changeset
|
84 See :hg:`help phase` for more information on manually manipulating phases. |