annotate mercurial/help/phases.txt @ 20689:401f9b661a2d

doc: show short description of each commands in generated documents Before this patch, short description of each commands is not shown in generated documents (HTML file and UNIX man page). This omitting may prevent users from understanding about commands. This patch show it as the 1st paragraph in the help section of each commands. This style is chosen because: - showing it as the section title in "command - short desc" style disallows referencing by "#command" in HTML file: in "en" locale, hyphen concatenated title is used as the section ID in HTML file for this style - showing it as the 1st paragraph in "command - short desc" style seems to be redundant: "command" appears also just before as the section title - showing it just after synopsis like "hg help command" seems not to be reasonable in UNIX man page This patch just writes short description ("d['desc'][0]") before "::", because it should be already "strip()"-ed in "get_desc()", or empty string for the command without description.
author FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
date Tue, 11 Mar 2014 14:36:40 +0900
parents f1a3ae7c15df
children 311eddddca49
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
15996
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
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
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
3
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
4 Phases are a system for tracking which changesets have been or should
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
5 be shared. This helps prevent common mistakes when modifying history
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
6 (for instance, with the mq or rebase extensions).
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
7
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
8 Each changeset in a repository is in one of the following phases:
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
9
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
10 - public : changeset is visible on a public server
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
11 - draft : changeset is not yet published
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
12 - secret : changeset should not be pushed, pulled, or cloned
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
13
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
14 These phases are ordered (public < draft < secret) and no changeset
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
15 can be in a lower phase than its ancestors. For instance, if a
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
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
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
18
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
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
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
21
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
22 For the most part, phases should work transparently. By default, a
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
23 changeset is created in the draft phase and is moved into the public
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
24 phase when it is pushed to another repository.
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
25
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
26 Once changesets become public, extensions like mq and rebase will
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
27 refuse to operate on them to prevent creating duplicate changesets.
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
28 Phases can also be manually manipulated with the :hg:`phase` command
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
29 if needed. See :hg:`help -v phase` for examples.
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
30
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
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
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
33
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
34 Normally, all servers are ``publishing`` by default. This means::
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
35
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
36 - all draft changesets that are pulled or cloned appear in phase
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
37 public on the client
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
38
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
39 - all draft changesets that are pushed appear as public on both
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
40 client and server
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
41
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
42 - secret changesets are neither pushed, pulled, or cloned
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
43
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
44 .. note::
20532
f1a3ae7c15df help: remove last occurrences of ".. note::" without two newlines
Simon Heimberg <simohe@besonet.ch>
parents: 20299
diff changeset
45
15996
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
46 Pulling a draft changeset from a publishing server does not mark it
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
47 as public on the server side due to the read-only nature of pull.
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
48
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
49 Sometimes it may be desirable to push and pull changesets in the draft
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
50 phase to share unfinished work. This can be done by setting a
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
51 repository to disable publishing in its configuration file::
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
52
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
53 [phases]
16000
25fa240139cb help: fix publish option spelling in phases topic
Matt Mackall <mpm@selenic.com>
parents: 15998
diff changeset
54 publish = False
15998
916de764b4f6 help/phases: remove trailing whitespace
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 15996
diff changeset
55
19295
73066ba46ec5 doc: reword "config file" to "configuration file"
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 18960
diff changeset
56 See :hg:`help config` for more information on configuration files.
15996
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
57
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
58 .. note::
20532
f1a3ae7c15df help: remove last occurrences of ".. note::" without two newlines
Simon Heimberg <simohe@besonet.ch>
parents: 20299
diff changeset
59
15996
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
60 Servers running older versions of Mercurial are treated as
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
61 publishing.
0455463655e0 help: add phases topic
Matt Mackall <mpm@selenic.com>
parents:
diff changeset
62
20299
b4b77909318f phases: add a formal note that hash of secret changeset may leak out
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 19959
diff changeset
63 .. note::
20532
f1a3ae7c15df help: remove last occurrences of ".. note::" without two newlines
Simon Heimberg <simohe@besonet.ch>
parents: 20299
diff changeset
64
20299
b4b77909318f phases: add a formal note that hash of secret changeset may leak out
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 19959
diff changeset
65 Changesets in secret phase are not exchanged with the server. This
b4b77909318f phases: add a formal note that hash of secret changeset may leak out
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 19959
diff changeset
66 applies to their content: file names, file contents, and changeset
b4b77909318f phases: add a formal note that hash of secret changeset may leak out
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 19959
diff changeset
67 metadata. For technical reasons, the identifier (e.g. d825e4025e39)
b4b77909318f phases: add a formal note that hash of secret changeset may leak out
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 19959
diff changeset
68 of the secret changeset may be communicated to the server.
b4b77909318f phases: add a formal note that hash of secret changeset may leak out
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 19959
diff changeset
69
b4b77909318f phases: add a formal note that hash of secret changeset may leak out
Pierre-Yves David <pierre-yves.david@ens-lyon.org>
parents: 19959
diff changeset
70
16011
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
71 Examples
17267
979b107eaea2 doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 16244
diff changeset
72 ========
16011
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 - list changesets in draft or secret phase::
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 hg log -r "not public()"
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 - change all secret changesets to draft::
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
79
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
80 hg phase --draft "secret()"
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
81
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
82 - 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
83
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
84 hg phase --force --draft .
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
85
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
86 - show a list of changeset revision and phase::
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
87
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
88 hg log --template "{rev} {phase}\n"
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
89
16041
6a959318c58e phases: add resync example to help topic
Matt Mackall <mpm@selenic.com>
parents: 16011
diff changeset
90 - 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
91
19959
9ef92384415c doc: use double quotation mark to quote arguments in examples for Windows users
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 19295
diff changeset
92 hg phase -fd "outgoing(URL)"
16041
6a959318c58e phases: add resync example to help topic
Matt Mackall <mpm@selenic.com>
parents: 16011
diff changeset
93
16011
f2c49d9dee57 help: add examples to phases topic
Matt Mackall <mpm@selenic.com>
parents: 16000
diff changeset
94 See :hg:`help phase` for more information on manually manipulating phases.