Kiln » TortoiseHg » TortoiseHg
Clone URL:  
Pushed to one repository · View In Graph Contained in 0.8.2, 0.8.3, and 0.9

stable doc: further commit chapter improvements

Changeset 52203f004e64…

Parent a1223d9898b5…

by Steve Borho

Changes to one file · Browse files at 52203f004e64 Showing diff from parent a1223d9898b5 Diff from another changeset...

Change 1 of 5 Show Changes Only doc/​source/​commit.txt Stacked
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
 
 
 
 
 
 
 
 
205
206
207
208
209
210
211
212
213
214
215
 
 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
 
 
 
 
 
 
 
 
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
 
 
 
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
 
 
 
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
 
 
 
 
 
 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
 
 
 
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
 
 
 
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
 TortoiseHg Commit Tool  ======================    .. module:: commit.dialog   :synopsis: Dialog used to perform commit    .. warning::   The win32text extension can cause trouble with hunk selection. This   has been resolved in Mercurial 1.3 and TortoiseHg 0.8, but requires   proper configuration. See   `issue #82 <http://bitbucket.org/tortoisehg/stable/issue/82/>`_.    The commit tool is an important part of TortoiseHg. It is, in fact, the  only component that is launchable from the first level of the context  menu. This is mainly because it is the most heavily used tool. Not only  can you commit your changes, but you can examine the state of your  working directory and perform most routine maintenance tasks (add new  files, record renames, manage the repository ignore filter, etc).    .. figure:: figures/commit.png   :alt: Commit dialog     Commit dialog    Features  --------    Walking across the toolbar, the buttons perform the following tasks:    :guilabel:`Refresh`   Reload the state of the working directory. It tries to retain file   check and selection state across refresh, but not hunks.  :guilabel:`Commit`   Commit selected diffs in checked files.  :guilabel:`Undo`   Undo (rollback) last immediate commit. Your commit message will be   available in the message history, so you can re-do the commit after   fixing whatever problem you noticed.  :guilabel:`Revert`   Revert checked files to last revisioned state.  :guilabel:`Add`   Add checked files that were in unknown '?' state. These files will   then be versioned as soon as they are committed.  :guilabel:`Move`   Move checked files to specified target directory. This move is done   with Mercurial's full knowledge.  :guilabel:`Remove`   Delete checked unversioned files and/or remove (mark as deleted) any   versioned files.    Below the toolbar are two other useful widgets:    :guilabel:`Branch name`   Shows the current branch name of the working directory. Normally   this is informational only, but you can create (open) a new branch   by changing this name before making a commit. Do not use this   feature unless you understand Mercurial's named branches.  :guilabel:`Recent Commit Messages`   A drop-down list of the 10 most recent commit messages. The behavior   of this drop-down has been tweaked in 0.7, and should behave   naturally.  :guilabel:`Patch name`   If you have enabled the MQ extension, there will also be a text   entry for a new patch name. Entering a name here will switch the   commit tool into 'QNew' mode where the working directory changes   will be applied to a new patch.      The file list has four columns:    1) A checkbox that indicates whether the file is selected for an   operation. The toolbar buttons only operate on checked files.   "Partially" selected files have a special check state. This column   header is checkable, it will toggle the file selection states.  2) The :guilabel:`st` column holds the status of the file, defined by   Mercurial's status command, one of 'MARD?IC'.  3) The :guilabel:`ms` column holds the merge state of the file, defined   by Mercurial's resolve command, one of ' RU'. See the merge section   below.  4) The canonical path of the file (relative to the repository root)    Below the file list are checkboxes that toggle the display of the  various classes of files {modified, added, removed, deleted, unknown,  clean, ignored}. These check boxes will be disabled if the commit tool  was given a specific set of files and/or directories.    *Removed* means a revisioned file has been marked as removed. *Deleted*  means a revisioned file is missing but Mercurial has not been told to  quit tracking that file. For instance, if you rename a revisioned file  in the explorer, the original filename will show up as deleted and the  new filename will show up as unknown. By right-clicking on the new  filename you can bring up the rename guessing dialog which can discover  the rename by comparing file contents and mark the old file as removed  and the new file as added while recording the whole operation as a  rename.    *Unknown* files are not tracked by Mercurial, but they also do not match  any ignore filters you have configured. Unknown files are shown by  default because they are usually files that need to be added to revision  control. It is recommended that you keep your ignore filters up to date  to ensure that is the case. The context menu of unknown files has an  option open the ignore pattern tool.    *Clean* files are tracked files that have not been modified, while  *Ignored* files are untracked files that match a configured ignore  pattern. Neither of those file types are shown by default, unless a the  user includes such a file in a selection (explorer) or provides the file  on the command line.      Change Selection (record)  -------------------------    So what does it mean when we say the commit button will commit the  selected diffs in checked files? Simple, the native TortoiseHg commit  tool supports change selection instrinsically in the diff browser. This  means that all of the changes you make to versioned files can be  individually selected to be included in the commit or left out of the  commit (but left in the working directory). Fans of darcs or  Mercurial's record extension will recognize this immediately.    When is this necessary?  ^^^^^^^^^^^^^^^^^^^^^^^    Most often, it is when you have made more than a single coherent change  to your source code and you would like to commit your changes piecemeal.  This can often be accomplished by filtering the list of files in each  commit, but there will be times when your changes intermingle in the  same set of files and that's when this change selection feature becomes  indespensable.    How does it work?  ^^^^^^^^^^^^^^^^^    By double-clicking on individual change hunks in the diff panel.  *Technically, any action which activates a change hunk row will toggle  it's selection status. The spacebar will also work.* When a hunk is  unselected, the syntax highlighting of the diff is disabled and the  background is turned gray. At the same time, the file's diff header is  updated to show the current selection state, the selected hunk count and  changed lines will be updated. Toggle the hunk a second time to reselect  it for inclusion in your commit.    When a file is partially selected for commit, it's icon is changed from  a checkbox to a radio button. At a glance at the file list, you should  be able to find which files are entirely included in the commit,  partially included, or excluded entirely.    What happens at commit time?  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^    The short answer is that the selected files and hunks are committed to  the repository and the unselected changes are left in your working  directory for the next commit.    The long answer is a little more complicated. What happens behind the  scenes is that the files which are partially selected are backed up in a  safe location, reverted to their last revisioned state, have their  selected change hunks applied back to them, committed, and then finally  recovered from backup (thus placing the rejected change hunks back into  the working copy).    For files which are not partially selected, the commit operation avoids  the entire *backup, revert, patch, commit, recover* round trip and  commits those files in place.    This longer answer is only interesting when something goes wrong, which  on Windows unfortunately has a probability greater than 0. If some  program (virus checker, compiler) locks your file in the middle of this  process you may see an error about a failed patch. These errors are  recoverable. Delete any new :file:`.rej` files and try the commit again.        Keyboard navigation  -------------------    :kbd:`Ctrl-Enter`   will trigger the commit  :kbd:`Ctrl-C`   In the diff panel will copy the currently highlighted (not selected,   but highlighted) diff hunks to the clipboard. These can be pasted   into a text buffer to generate any arbitrary patch based from the   changes in your working directory.    The code which copies the hunks to the clipboard is intelligent about  diff headers. If your highlighted list includes a hunk from a file but  not it's file diff header, the diff header will be added to the  clipboard in the appropriate location in the stream to make the  clipboard contents always be a valid patch.      File Context Menus  ------------------    By right clicking on files in the file list, you will get a context menu  of commands that are applicable to the selected file. If you configure a -visual editor in -:menuselection:`Settings --> Global --> TortoiseHg --> Visual Editor` -there will be an option to open the file in your editor. For unknown **?** -files, the context menu will allow you to detect renames (if you think -the unknown file was a copy or rename of a revisioned file) or configure -the repository's ignore filter (if the file should never be revisioned -and you want Mercurial to ignore it). +visual editor (in +:menuselection:`Global Settings --> TortoiseHg --> Visual Editor`) +there will be a menu option to open the file in your editor. + +For unknown **?** files, the context menu will allow you to detect +renames (if you think the unknown file is a copy or rename of a +revisioned file) or to configure the repository's ignore filter (if the +unknown file should never be revisioned and you want Mercurial to ignore +it).      Merges  ------    The commit tool has a special mode when it is opened in a repository  that is in a merged state (technically, this means the current working  directory has two parent revisions). The file list has no checkboxes and  the diff pane does not allow selections. The commit 'manifest' is -essentially immutable, you must commit the entire working directory -after a merge. +essentially immutable, since you must commit the entire working +directory after a merge.    The merge state *ms* column is especially useful in this mode. Files  that are marked with *R* are files where Mercurial and/or the user have  successfully merged (resolved) changes from both branches. Files that  are marked with *U* have unresolved changes. You can use the *resolve*  context menu option to restart the merge for that file, or you can use  the *edit* context menu option to resolve the conflict by hand. When the  conflict has been resolved, you use the *mark resolved* context menu  option, which changes the file's merge state to *R*.    Mercurial will not allow you to commit a merge if any files have  unresolved *U* merge states.    For your reference, *local* is the revision you had checked out when you  started the merge and *other* is the revision you merged with.   +To undo a failed merge attempt, you must tell Mercurial to remove the +second parent from your working directory. This usually means +performing a clean update of the first parent. The merge tool has an +:guilabel:`Undo` button which does exactly that. The recovery tool also +has a :guilabel:`Clean` button that does the same thing. + +Once you have your working directory back at one parent revision, you +may start the merge process again. +    Commit Message Format  ---------------------    If your project has guidelines for commit message format, you can  configure those in the settings tool. Once configured, the commit tool  will inform you if you try to commit with a non-conforming message.  There is also an :guilabel:`apply format` context menu option available  on the commit message pane that will try to enforce your policy.    MQ patches  ----------    Many advanced Mercurial users use the MQ extension to manage a patch  queue. TortoiseHg does not offer much in the way of support for MQ, but  the commit tool will at least recognize when a patch is applied. When a  patch is applied, the usual commit command will not work, so the commit  tool enters *patch refresh* mode. The title bar will say "refreshing  patch *patchname*" and the patch comment will appear in the commit  message pane.    The commit tool will present the entire contents of the top patch  including any changes that are in your working directory (un-refreshed  changes). This is essentially what the qdiff command would show you.  There is, in fact, no way to get just the working copy diffs beyond  running :command:`hg diff` on the command line. The reason the dialog  operates in this mode is that it allow you to use the integrated change  selection features to move changes into or out of the top patch. You can  move entire files or single changes in or out of the patch.    The :guilabel:`Commit` button, which has been renamed :guilabel:`QRefresh`  in this context, it will refresh the top patch with just the changes you -have selected (including the patch description). This may be a bit confusing at first -because the changes you leave out of the patch are still going to be in -the working directory after the refresh, so it will look like nothing -has changed. +have selected (including the patch description). This may be a bit +confusing at first because the changes you leave out of the patch are +still going to be in the working directory after the refresh, so it will +look like nothing has changed.    So, in summary, using MQ with TortoiseHg is still almost entirely a  command line operation, but you can use :command:`hgtk ci` to refresh your  patches and take advantage of our excellent change selection support.    QNew Mode  ---------    Newly added in 0.8, the commit tool can be used to create a new patch  for your patch queue. If you have the MQ extension enabled, a text  entry will be inserted between the branch maintenance button and the  message history drop-down box. If you enter a filename in this entry  the commit tool will switch out of *commit* or *qrefresh* mode into  *qnew* mode. In *qnew* mode, the commit tool shows only working  directory modifications (the changes that would typically get added to a  new patch by :command:`hg qnew -f`). The :guilabel:`Commit` button will  change into a :guilabel:`QNew` button as well, to make the mode switch  more obvious.   -When the :guilabel:`QNew` button is pressed, the selected change hunks are written -into a new patch (given the filename you specified), and the dialog is -refreshed. At refresh, the commit tool will obviously switch to -*qrefresh* mode since there will now be at least one applied patch. +When the :guilabel:`QNew` button is pressed, the selected change hunks +are written into a new patch (given the filename you specified), and the +dialog is refreshed. At refresh, the commit tool will obviously switch +to *qrefresh* mode since there will now be at least one applied patch.    You may give the new patch a commit message at the initial *qnew* event,  or you can do it now by using the *qrefresh* feature.    If you left change hunks out of the new patch, they will appear to be in  the new patch anyway because of the way *qrefresh* mode shows the sum of  both the top patch and the working directory changes. If you enter a  new patch name again, and switch the commit tool into *qnew* mode again,  you will see the changes that you left in the working directory.      Configurables  -------------    :menuselection:`Commit --> Username`   Sets username associated with your commits  :menuselection:`Commit --> External Tool`   Allows you to select Qct as the your commit tool [DEPRECATED]  :menuselection:`Commit --> Summary Line Length`   Configures a 'policy' limit for summary lines  :menuselection:`Commit --> Message Line Length`   Configures a 'policy' limit for message lines  :menuselection:`TortoiseHg --> Bottom Diffs`   Toggles diff pane from left to below file list  :menuselection:`TortoiseHg --> Max Diff Size`   Configures the diff size limit    External tool configuration is deprecated and will be removed in 0.9    From command line  -----------------    The commit tool can be started from command line ::     hgtk commit    or ::     hgtk ci    The syntax is ::     hgtk commit [OPTIONS] [FILES]    where [FILES] is one or more file that must be commited, if no files are  specified TortoiseHg commits all the modified files, and valid [OPTIONS] are:    ``-d``, ``--date``   Use the specified date as commit date, if not specified the current date   and time is used. For a quick help on the format of date type::     hgtk help dates     or ::     hg help dates    ``-u``, ``--user``   Use the specified user name as author of the commit, if not specified the   user set in repository or global settings is used.      Changes since 0.7  -----------------    * The :guilabel:`Show Diff` button has been removed. Diffs are always shown.  * The commit tool no longer shows all diffs at startup. Only the first   currently selected file is shown.  * Added support for closing a named branch  * The commit tool is now launchable from the merge dialog  * The message pane context menu now has options for inserting selected   filenames, and configuring/applying a layout format.  * :guilabel:`Ctrl-O` keyboard accelerator for triggering commit has been   replaced with :guilabel:`Ctrl-Enter` accelerator which is common to   many THG dialogs  * Support for two-parent state (merging) has been improved, especially   the file context menus.  * There is now a limit on the size of files that will be diffed by the commit   and changelog tools. Files above this size will only show a message   indicating why the file was not diffed. This limit (default: 1MB) is   configurable (per-repository if necessary) via the settings dialog   :menuselection:`TortoiseHg --> Max Diff Size`.  * You can specify the commiter and date via the command line: see   :command:`hgtk commit -h` for details  * The :file:`qct.py` extension file is no longer bundled. It must be   downloaded separately if you wish to use Qct.      Changes since 0.6  -----------------    Large changes were made to the commit tool in the 0.7 release. The  previous default tool, Qct, was unbundled and TortoiseHg's native commit  tool was promoted to the top spot. See the `FAQ <http://bitbucket.org/tortoisehg/stable/wiki/FAQ#tortoisehg-faq>`_  for instructions on recovering Qct, if you must, but we suggest you first  read the rest of this page to understand how the native tool now measures up.    The default layout of the native commit tool is different than Qct. The  file list is on the left side of the diff panel. If you prefer the Qct  layout, set the :menuselection:`Commit --> Bottom Diffs` configuration  item to :guilabel:`True` in the TortoiseHg settings dialog. This change  will take affect the next time you start the commit tool.    Also different in the native commit tool is that all the diffs in the  working directory are shown in the diff panel at startup. Selecting  files in the file list will zoom to that file's diffs in the diff panel.  In Qct, selecting a file would refresh the diff pane with just that  file's diffs (which was also the behavior of the native tool before  0.7). The new behavior gives a better view of what the changeset being  committed will look like (it matches more closely to the changelog  view).    New in the native commit tool in 0.7 is the auto-checking of  *M* odified, *A* dded, and *R* emoved files at startup as these are  all change types that are automatically included in any :command:`hg commit`  command with no arguments. Similarly, unknown *?* files are shown by  default at startup since that is standard behaviour for the :command:`hg status`  command. Qct was already doing both of these things, so this  will come as no surprise to Qct users.    .. vim: noet ts=4