Merge lp:~ian-clatworthy/bzr/commit-help into lp:~bzr/bzr/trunk-old

Proposed by Ian Clatworthy on 2009-05-12
Status: Merged
Merged at revision: not available
Proposed branch: lp:~ian-clatworthy/bzr/commit-help
Merge into: lp:~bzr/bzr/trunk-old
Diff against target: 158 lines
To merge this branch: bzr merge lp:~ian-clatworthy/bzr/commit-help
Reviewer Review Type Date Requested Status
Robert Collins (community) 2009-05-12 Approve on 2009-05-12
Review via email: mp+6454@code.launchpad.net
To post a comment you must log in.
Ian Clatworthy (ian-clatworthy) wrote :

Some drive-by improvements to the commit help and a commit error message.

Robert Collins (lifeless) wrote :

 review approve

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'bzrlib/builtins.py'
2--- bzrlib/builtins.py 2009-05-11 18:35:20 +0000
3+++ bzrlib/builtins.py 2009-05-12 13:35:10 +0000
4@@ -2727,42 +2727,75 @@
5 class cmd_commit(Command):
6 """Commit changes into a new revision.
7
8- If no arguments are given, the entire tree is committed.
9-
10- If selected files are specified, only changes to those files are
11- committed. If a directory is specified then the directory and everything
12- within it is committed.
13-
14- When excludes are given, they take precedence over selected files.
15- For example, too commit only changes within foo, but not changes within
16- foo/bar::
17-
18- bzr commit foo -x foo/bar
19-
20- If author of the change is not the same person as the committer, you can
21- specify the author's name using the --author option. The name should be
22- in the same format as a committer-id, e.g. "John Doe <jdoe@example.com>".
23- If there is more than one author of the change you can specify the option
24- multiple times, once for each author.
25-
26- A selected-file commit may fail in some cases where the committed
27- tree would be invalid. Consider::
28-
29- bzr init foo
30- mkdir foo/bar
31- bzr add foo/bar
32- bzr commit foo -m "committing foo"
33- bzr mv foo/bar foo/baz
34- mkdir foo/bar
35- bzr add foo/bar
36- bzr commit foo/bar -m "committing bar but not baz"
37-
38- In the example above, the last commit will fail by design. This gives
39- the user the opportunity to decide whether they want to commit the
40- rename at the same time, separately first, or not at all. (As a general
41- rule, when in doubt, Bazaar has a policy of Doing the Safe Thing.)
42-
43- Note: A selected-file commit after a merge is not yet supported.
44+ An explanatory message needs to be given for each commit. This is
45+ often done by using the --message option (getting the message from the
46+ command line) or by using the --file option (getting the message from
47+ a file). If neither of these options is given, an editor is opened for
48+ the user to enter the message. To see the changed files in the
49+ boilerplate text loaded into the editor, use the --show-diff option.
50+
51+ By default, the entire tree is committed and the person doing the
52+ commit is assumed to be the author. These defaults can be overridden
53+ as explained below.
54+
55+ :Selective commits:
56+
57+ If selected files are specified, only changes to those files are
58+ committed. If a directory is specified then the directory and
59+ everything within it is committed.
60+
61+ When excludes are given, they take precedence over selected files.
62+ For example, to commit only changes within foo, but not changes
63+ within foo/bar::
64+
65+ bzr commit foo -x foo/bar
66+
67+ A selective commit after a merge is not yet supported.
68+
69+ :Custom authors:
70+
71+ If the author of the change is not the same person as the committer,
72+ you can specify the author's name using the --author option. The
73+ name should be in the same format as a committer-id, e.g.
74+ "John Doe <jdoe@example.com>". If there is more than one author of
75+ the change you can specify the option multiple times, once for each
76+ author.
77+
78+ :Checks:
79+
80+ A common mistake is to forget to add a new file or directory before
81+ running the commit command. The --strict option checks for unknown
82+ files and aborts the commit if any are found. More advanced pre-commit
83+ checks can be implemented by defining hooks. See ``bzr help hooks``
84+ for details.
85+
86+ :Things to note:
87+
88+ If you accidentially commit the wrong changes or make a spelling
89+ mistake in the commit message say, you can use the uncommit command
90+ to undo it. See ``bzr help uncommit`` for details.
91+
92+ Hooks can also be configured to run after a commit. This allows you
93+ to trigger updates to external systems like bug trackers. The --fixes
94+ option can be used to record the association between a revision and
95+ one or more bugs. See ``bzr help bugs`` for details.
96+
97+ A selective commit may fail in some cases where the committed
98+ tree would be invalid. Consider::
99+
100+ bzr init foo
101+ mkdir foo/bar
102+ bzr add foo/bar
103+ bzr commit foo -m "committing foo"
104+ bzr mv foo/bar foo/baz
105+ mkdir foo/bar
106+ bzr add foo/bar
107+ bzr commit foo/bar -m "committing bar but not baz"
108+
109+ In the example above, the last commit will fail by design. This gives
110+ the user the opportunity to decide whether they want to commit the
111+ rename at the same time, separately first, or not at all. (As a general
112+ rule, when in doubt, Bazaar has a policy of Doing the Safe Thing.)
113 """
114 # TODO: Run hooks on tree to-be-committed, and after commit.
115
116@@ -2773,7 +2806,7 @@
117
118 # XXX: verbose currently does nothing
119
120- _see_also = ['bugs', 'uncommit']
121+ _see_also = ['add', 'bugs', 'hooks', 'uncommit']
122 takes_args = ['selected*']
123 takes_options = [
124 ListOption('exclude', type=str, short_name='x',
125@@ -2900,8 +2933,8 @@
126 except PointlessCommit:
127 # FIXME: This should really happen before the file is read in;
128 # perhaps prepare the commit; get the message; then actually commit
129- raise errors.BzrCommandError("no changes to commit."
130- " use --unchanged to commit anyhow")
131+ raise errors.BzrCommandError("No changes to commit."
132+ " Use --unchanged to commit anyhow.")
133 except ConflictsInTree:
134 raise errors.BzrCommandError('Conflicts detected in working '
135 'tree. Use "bzr conflicts" to list, "bzr resolve FILE" to'
136
137=== modified file 'bzrlib/tests/blackbox/test_commit.py'
138--- bzrlib/tests/blackbox/test_commit.py 2009-03-27 04:10:25 +0000
139+++ bzrlib/tests/blackbox/test_commit.py 2009-05-12 13:35:11 +0000
140@@ -43,8 +43,8 @@
141 self.build_tree(['hello.txt'])
142 out,err = self.run_bzr('commit -m empty', retcode=3)
143 self.assertEqual('', out)
144- self.assertContainsRe(err, 'bzr: ERROR: no changes to commit\.'
145- ' use --unchanged to commit anyhow\n')
146+ self.assertContainsRe(err, 'bzr: ERROR: No changes to commit\.'
147+ ' Use --unchanged to commit anyhow.\n')
148
149 def test_commit_success(self):
150 """Successful commit should not leave behind a bzr-commit-* file"""
151@@ -395,7 +395,7 @@
152
153 # With no changes, it should just be 'no changes'
154 # Make sure that commit is failing because there is nothing to do
155- self.run_bzr_error(['no changes to commit'],
156+ self.run_bzr_error(['No changes to commit'],
157 'commit --strict -m no-changes',
158 working_dir='tree')
159