/doc/source/workbench.txt

  1Changelog
  2=========
  3
  4.. module:: changelog.dialog
  5	:synopsis: Dialog used to view log
  6
  7The changelog tool (*also known as the repository explorer*) is
  8used to visualize the revision history of your repository and to perform
  9any maintenence tasks that involve changesets. It presents a graph of
 10the revision history, showing the parent/child relationship of each
 11change. At each revision you can view the files that were modified and
 12the contents of those changes.
 13
 14.. figure:: figures/log.png
 15	:alt: Changelog
 16
 17	Changelog viewer dialog with main toolbar hidden
 18
 19The changelog tool has a menu bar for accessing tool functions and for
 20launching other tools.
 21
 22	:guilabel:`Tools`
 23		Launch other TortoiseHg tools as separate processes
 24	:guilabel:`View`
 25		Toggle the visibility of various features, or refresh views
 26	:guilabel:`Navigate`
 27		Select specific changesets in your repository history
 28	:guilabel:`Synchronize`
 29		Access synchronization functions, more below
 30	:guilabel:`Help`
 31		Help contents shows this web page.  About shows TortoiseHg
 32		version info
 33
 34The toolbar buttons from left to right:
 35
 36	:guilabel:`Refresh`
 37		Reload the revision history (if you commit in another window, etc)
 38	:guilabel:`Reset Marks`
 39		Remove 'new', 'incoming', and 'outgoing' revision marks and refresh
 40	:guilabel:`Patch Queue`
 41		Toggles the display of the MQ pane.  This button is only visible
 42		when the MQ extension has been enabled by the user.
 43	:guilabel:`Commit`
 44		Launch the commit tool in a separate process
 45	:guilabel:`Datamine`
 46		Launch the data mining tool in a separate process
 47	:guilabel:`Recovery`
 48		Launch the recovery dialog in a separate process
 49	:guilabel:`Web Server`
 50		Launch the web server dialog in a separate process
 51	:guilabel:`Shelve`
 52		Launch the shelve tool in a separate process
 53	:guilabel:`Patch Branch`
 54		Toggles the display of the Patch Branch pane.  This button is only
 55		visible when the pbranch extension has been enabled by the user.
 56	:guilabel:`Load more`
 57		Load the next N revisions into the graph
 58	:guilabel:`Load all`
 59		Load all remaining revisions into the graph
 60
 61Sync Bar
 62---------
 63
 64.. figure:: figures/syncbar.png
 65	:alt: Changelog
 66
 67	Synchronization features in changelog tool
 68
 69From left to right...
 70
 71	:guilabel:`Incoming`
 72		Download incoming changesets from the remote repository, store
 73		them in a temporary bundle file, then enter bundle preview mode
 74		with the incoming changes applied.  Incoming changesets will
 75		have a 'down' arrow in the revision graph.
 76	:guilabel:`Accept`
 77		Accept (pull) the changesets from the previewed bundle.  This
 78		button is only sensitive when previewing a changeset bundle.
 79		The after-pull effect is respected after pulling from a bundle.
 80	:guilabel:`Reject`
 81		Reject the changesets from the previewed bundle and exit preview
 82		mode.  This button is only sensitive when previewing a changeset
 83		bundle.
 84	:guilabel:`Pull`
 85		Pull incoming changesets from the remote repository, then apply
 86		after-pull effect (update, fetch, or rebase).
 87	:guilabel:`Import`
 88		Open the import dialog to import one or more patches
 89	:guilabel:`Outgoing`
 90		Determine outgoing changesets that would be pushed to the
 91		remote repository.  Outgoing changesets are marked with an 'up'
 92		arrow.
 93	:guilabel:`Push`
 94		Push outgoing changesets to the remote repository.
 95	:guilabel:`Email`
 96		Email outgoing changesets to the remote repository.
 97	:guilabel:`Stop`
 98		Stop current transaction.  The button is only sensitive during
 99		outgoing commands.
100
101To the right of the :guilabel:`Stop` button is a combo box containing
102all of the configured peer repository paths for the current repository.
103The default path is selected at startup, if it has been configured.
104See `hg.1.html#urls <http://www.selenic.com/mercurial/hg.1.html#urls>`_  for
105details on specifying remote repository URLs.
106
107To the right of the path combo box is the :guilabel:`After Pull` combo
108that selects the operation which is performed after every pull operation
109triggered by the sync bar.  The user must have the rebase extension
110enabled in order for that option to be available in the after pull
111combo.  The same is true of the fetch extension and it's post pull
112operation.
113
114To the right of the :guilabel:`After Pull` combo is the
115:guilabel:`Settings` button.  It opens the repository settings tool on
116the :guilabel:`Sync` tab where the after pull configurable and peer
117repository paths can be configured.
118
119Changesets which are added to the repository after the changelog tool
120was opened are marked with green stars in the graph.  This includes
121recent commits, pulled changesets, and applied patches.
122
123.. note::
124	To clear the new, incoming, and outgoing marks from the changeset
125	graph, use :guilabel:`View -> Reset Marks`
126
127Search Bar
128----------
129
130.. figure:: figures/searchbar.png
131	:alt: Changelog
132
133	Filter features in changelog tool
134
135The search bar allows one to quickly filter the changesets panel.
136Buttons from right to left...
137
138	:guilabel:`All`
139		Show all changesets in the respository.  Essentially removes all
140		filters.
141	:guilabel:`Tagged`
142		Show only changesets with tags.
143	:guilabel:`Ancestry`
144		Show only changesets that are ancestors of the currently
145		selected changeset.  This option is only sensitive when a
146		revision is selected.
147	:guilabel:`Parents`
148		Show only the working directory parent revisions.  Unless a
149		merge is in progress, this will be only one revision.
150	:guilabel:`Heads`
151		Show only repository heads (changesets without any child
152		revisions).
153	:guilabel:`Merges`
154		Show only merge changesets (changesets with two parents)
155	:guilabel:`Hide Merges`
156		A toggle button, not a radio like the other buttons in the
157		search bar, which toggles the display of merge changesets.
158	:guilabel:`Branches`
159		A combo box with the list of named branches in your repository.
160		See :guilabel:`Repo Settings -> Changelog -> Dead Branches` for
161		a method to prune names from this combo box.
162	:guilabel:`Custom Filter Combo`
163		Finally there is a combo box that selects among the various
164		filter types that can be manually specified.
165
166To specify a custom filter, the user selects the filter type, enters
167the search text of that type, and then hits return in the text entry.
168
169	:guilabel:`Revision Set`
170		Parse the user text as a revision set.  See
171		`hg.1.html#revisions <http://www.selenic.com/mercurial/hg.1.html#revsets>`_ 
172		for details on how to specify revision sets.
173	:guilabel:`File Patterns`
174		Parse the user text as a file pattern glob, unless the user text
175		is prefixed with a pattern type like *regexp:*.  See
176		`hg.1.html#patterns <http://www.selenic.com/mercurial/hg.1.html#patterns>`_ 
177		for details on how to specify file patterns.
178	:guilabel:`Keywords`
179		Parse the user text as a keyword pattern that should be matched
180		against changeset meta data like comitter, message, etc.
181	:guilabel:`Date`
182		Parse the user text as a date range.  See
183		`hg.1.html#dates <http://www.selenic.com/mercurial/hg.1.html#dates>`_ 
184		for details on how to specify date ranges.
185	:guilabel:`User`
186		Parse the user text as a user / comitter name.
187
188The filter entry has a combo box which stores the history of searches.
189Selecting an item from the drop down list will apply that filter.
190
191Revision Graph Details
192----------------------
193
194The graph column shows the child-parent relationships between revisions
195in your repository history.  This column auto-sizes for as many lines of
196ancestry that are required to visualize the revisions you have loaded.
197The column has an initial hard-limit width to prevent some degenerative
198cases from breaking the viewer, but can be resized after refreshes.
199
200Performance Implications
201------------------------
202
203There are some Repository Explorer features that should probably be
204avoided in large repositories.
205
206* :menuselection:`View -> Color By Branch` 
207	This option requires the log viewer to query the branch name of
208	every revision in order to draw the graph.  It can cause refreshes
209	to be slow.
210
211* :menuselection:`View -> Compact Graph` 
212	This option can cause refresh to be slower than the default setting.
213	Also be aware that enabling this feature makes the graph lines less
214	accurate.  The feature trades merge parent accuracy for horizontal
215	screen space.
216
217* Column :guilabel:`Changes` 
218	This column can be expensive to calculate on repositories with large
219	working copies, causing both refreshes and scrolling to be slow.
220
221
222Revision Context Menus
223----------------------
224
225Right-clicking on a revision in the (top) graph pane will bring up the
226revision context menu.
227
228	:guilabel:`Visualize Change`
229		Open this change in your visual diff tool
230	:guilabel:`Display Change`
231		Open this changeset in the changeset browser (more below)
232	:guilabel:`Diff to Local`
233		Display changes (visual diff) between this revision and your
234		current working directory
235	:guilabel:`Copy Hash`
236		Copy current revision's full hash to the clipboard
237	:guilabel:`Push to Here`
238		Performs the equivalent of 'push -r <rev>'.  This option is only
239		available on changesets marked as outgoing.
240	:guilabel:`Push this Branch`
241		Performs the equivalent of 'push --new-branch --branch <branch>'.
242		This option is only available on changesets marked as outgoing.
243	:guilabel:`Update...`
244		Update your working directory to this revision. Opens the
245		TortoiseHg update dialog with this revision selected.
246	:guilabel:`Merge With...`
247		Merge with this revision. Opens the TortoiseHg merge dialog with
248		this revision selected.
249	:guilabel:`Backout...`
250		Create a backout changeset for selected revision
251	:guilabel:`Revert`
252		Revert working copy to this revision's contents, without
253		updating working directory parent revision. Use with care.
254	:guilabel:`Export`
255		:guilabel:`Export Patch`
256			Generate a patch file containing this revision's changes
257		:guilabel:`Email Patch`
258			Send this revision's changes to email recipient.  Opens the
259			TortoiseHg email dialog with this revision selected.
260		:guilabel:`Bundle rev:tip`
261			Create a bundle with all revs from selected to tip
262		:guilabel:`Archive...`
263			Open the archive dialog for this revision, allowing user to
264			generate a backup copy of the repository at that revision.
265	:guilabel:`Tag`
266		:guilabel:`Add/Remove Tag`
267			Open the TortoiseHg tag dialog with this revision selected
268		:guilabel:`Add/Move/Remove Bookmark`
269			Open the TortoiseHg bookmark dialog with this revision selected
270			*This option requires the boomarks extension to be enabled*
271		:guilabel:`Rename Bookmark`
272			Open the TortoiseHg bookmark rename dialog
273			*This option requires the boomarks extension to be enabled*
274	:guilabel:`Mercurial Queues`
275		:guilabel:`Import revision to MQ`
276			Import selected revision into the current patch queue.  Only
277			valid for qbase or checked out head revision.  *Only visible
278			when MQ is enabled*
279		:guilabel:`Strip Revision...`
280			Remove the selected revision and all of it's descendants from the
281			repository [#rcm1]_ *Only visible when MQ is enabled*
282	:guilabel:`Transplant to local`
283		Transplant selected revision onto the current working parent.
284		*Only visible when the transplant extension is enabled*
285	:guilabel:`Bisect`
286		:guilabel:`Reset`
287			Reset bisect state. See `bisect <#id10>`_ section below.
288		:guilabel:`Mark as Good`
289			Mark changeset as good
290		:guilabel:`Mark as Bad`
291			Mark changeset as bad
292		:guilabel:`Skip Testing`
293			Skip testing this changeset
294
295If you right-click on a row other than the one that was currently
296selected, you get a secondary context menu which defines commands that
297operation on revision ranges.
298
299	:guilabel:`Diff with selected`
300		Opens status viewer with cumulative changes of the range of
301		changesets.  The status viewer allows cherry picked changes to
302		be saved to a file.
303	:guilabel:`Visual Diff with selected`
304		Opens visual diff window with cumulative changes of the range
305		of changesets.  See also menuselection:`Global Settings -->
306		TortoiseHg --> Visual Diff Tool`
307	:guilabel:`Email from here to selected`
308		Opens email dialog with range of changesets.
309	:guilabel:`Bundle from here to selected`
310		Creates a bundle file with range of changesets.
311	:guilabel:`Export patches from here to selected`
312		Creates a patch file for each changeset in selected range.
313	:guilabel:`Merge with ...`
314		Merges this revision with the other selected revision.  If
315		neither revision is currently checked out, the merge dialog will
316		be forced to update to the first selected revision before
317		starting the merge.  This will fail if the working directory is
318		not clean.
319	:guilabel:`Transplant revision range to local`
320		Transplant selected range of changesets on to current working
321		parent revision. *Only visible when the transplant extension is
322		enabled*
323	:guilabel:`Rebase on top of selected`
324		Rebase selected changeset and ancestors on top of original
325		selected revision.  *Only visible when the rebase extension is
326		enabled*
327	:guilabel:`Import from here to selected to MQ`
328		Import selected revision range into the current patch queue.
329		*Only visible when MQ is enabled*
330	:guilabel:`Select common ancestor`
331		Selects (highlights) the common ancestor of the two selected
332		revisions.  Helpful, when reviewing merges.
333
334.. [#rcm1] The strip command will store the stripped revisions in a bundle file
335		that can later be reapplied.
336		See also `EditingHistory <http://mercurial.selenic.com/wiki/EditingHistory>`_.
337
338File Context Menus
339------------------
340
341Right-clicking on filenames in the file list (bottom left) pane will
342bring up a context menu for the selected file:
343
344	:guilabel:`Visual Diff`
345		Open this revision of the file in your visual diff tool
346	:guilabel:`Diff to Local`
347		Visualize differences between this revision and your checked
348		out version
349	:guilabel:`View at Revision`
350		Open this revision of the file in your visual editor [#flcm1]_
351	:guilabel:`Save at Revision`
352		Write this revision of the file to specified location
353	:guilabel:`File History`
354		Show revisions that modified this file [#flcm2]_
355	:guilabel:`Annotate File`
356		Open this file in the datamine app, annotated at this revision
357	:guilabel:`Revert File Contents`
358		Checkout this specific revision of this file [#flcm3]_
359 
360.. [#flcm1] :menuselection:`Global Settings --> TortoiseHg --> Visual Editor`
361.. [#flcm2] Does not show revisions where a file was deleted, as this is only a
362            manifest change, it does not modify the file's history.
363.. [#flcm3] The new contents will appear as local changes and must be committed.
364
365
366Changeset browser
367-----------------
368
369The changeset browser will only show a single file's diffs at a time, as
370a performance optimization.  If you would like to see all of the file
371diffs at once, click on the :guilabel:`[All Files]` row.  The changeset
372browser will also skip displaying diffs for files which are above a
373maximum limit. See
374:menuselection:`Global Settings --> TortoiseHg --> Max Diff Size`.  The
375size limit can be temporarily disabled by toggling :menuselection:`View
376-> Ignore Max Diff Size`.
377
378The changelog and datamine tools can open the changeset browser to view
379a single revision or the combined effect of a range of revisions. The
380changeset browser is very similar to the commit and shelve tools. It has
381a file list on the left of all files that have been changed, and a diff
382pane on the right with the changes to each file.
383
384The diff pane is tabbed and allows one to select files and hunks that
385you wish to extract from the changeset(s) you are browsing and write
386them to a patch file using the :guilabel:`Save as` toolbar button.  This
387is a very efficient way to cherry pick changes from a repository.  This
388changeset browser also supports the :kbd:`Ctrl-C` keyboard accelerator
389to copy hightlighted diff hunks to the clipboard.
390
391Unfortunately, TortoiseHg still does not have a dialog for importing
392patches into a repository, so this must be done on the command line with
393the :command:`hg import` command.
394
395Message Parsing
396---------------
397
398New in TortoiseHg 1.0, the repository browser will detect and underline
399changeset hashes, HTTP(s) URLs, and bug report identifiers inside
400changeset messages.  These underlined phrases are clickable links.
401
402Every word-boundary delimited string of 12 or 40 characters from the
403range [0-9a-f] is considered a changeset link. Clicking on it in the
404repository explorer will jump to the given changeset if possible.
405
406HTTP and HTTPS URLs are similarly turned into clickable links which are
407opened in your default web browser.
408
409Issue tracker links are enabled when configured in the tortoisehg
410section of your configuration files.  Since only a single issue tracker
411can be configured at a time, it is typically configured in the
412repository's :file:`.hg/hgrc` file.  There are two keys: issue.regex and
413issue.link. The first defines the regex to match when picking up issue
414numbers, while the second defines the command to run when an issue
415number is recognized.
416
417You may include groups in issue.regex, and corresponding {n} tokens in
418issue.link (where n is a non-negative integer). {0} refers to the entire
419string matched by issue.regex, while {1} refers to the first group and
420so on. If no {n} tokens are found in issue.link, the entire matched
421string is appended instead.
422
423Examples::
424
425	BitBucket:
426	issue.regex = #(\d+)\b
427	issue.link = http://bitbucket.org/<your project and repo>/issue/{1}/
428
429	Mercurial:
430	issue.regex = \bissue\d+\b
431	issue.link = http://mercurial.selenic.com/bts/
432
433Bisect
434------
435
436TortoiseHg 1.0 introduced support for bisect bug searching to help find
437changesets which introduce problems. To use, mark the earliest changeset
438you know exhibits the problem as bad, then mark the latest changeset
439which is free from the problem as good.  The changelog tool will select
440a changeset for you to test.  Once you have performed tests, mark the
441changeset as good or bad, and bisect will either update to another
442candidate changeset or announce that it has found the bad revision.
443
444As a shortcut, you can also mark a revision as good or bad without
445checking it out first.
446
447For more automated bisecting, you must use the Mercurial command line
448and provide an automated test that can build and run a changeset and
449return 0-good, 125-skip, or 127-abort, or anything else to mean bad.
450See the :command:`hg bisect` command help for more information.
451
452
453Keyboard navigation
454-------------------
455
456:kbd:`Ctrl-P`
457	Zoom to the working directory parent revision
458:kbd:`Ctrl-D`
459	Display visual diffs for selected changeset or file
460:kbd:`Ctrl-R`
461	Refresh repository contents
462:kbd:`Ctrl-G`
463	Go to a specific revision
464
465
466Configurables
467-------------
468
469The changelog browser has a few configurable options that can be set in
470the TortoiseHg Settings dialog on the Changelog tab.
471
472	:guilabel:`Author coloring`
473		If true, each author's changeset will be given a unique color
474	:guilabel:`Long Summary`
475		Concatenate commit message lines until 80 chars are reached
476	:guilabel:`Graph batch limit`
477		Number of revisions to read in each batch load
478	:guilabel:`Copy Hash`
479		Copy a revision's changeset id hash to the clipboard when selected
480		[DEPRECATED]
481	:guilabel:`Dead Branches`
482		Comma separated list of branch names that should be ignored
483		when building a list of branch names for a repository.
484	:guilabel:`Branch Colors`
485		Space separated list of branch names and colors on the
486		form branch:#XXXXXX. Spaces and colons in the branch name must be
487		escaped using a backslash (\\). Likewise some other characters
488		can be escaped in this way, e.g. \\u0040 will be decoded to the
489		@ character, and \\n to a linefeed.
490	:guilabel:`Hide Tags`
491		Space separated list of tags that will not be shown.  Useful
492		example: Specify "qbase qparent qtip" to hide the standard tags
493		inserted by the Mercurial Queues Extension.
494	:guilabel:`Use Expander`
495		Show changeset details within an expander.  When contained
496		within the expander, the details do not scroll with the
497		changeset contents.
498
499The exact colors given to particular users can be configured by adding
500lines like these to your :file:`Mercurial.ini` file: ::
501
502	[tortoisehg]
503	authorcolor.USERNAME = color
504
505The changelog browser also respects the following settings on the
506TortoiseHg tab:
507
508	:guilabel:`Tab Width`
509		Number of spaces to expand tabs in diffs
510	:guilabel:`Max Diff Size`
511		Maximum size of file to be diffed
512	:guilabel:`Bottom Diffs`
513		Show diffs below file list
514
515
516From command line
517-----------------
518
519The changelog viewer can be started from command line ::
520
521	hgtk log [OPTIONS] [FILE]
522
523	aliases: history
524
525	changelog viewer
526
527	options:
528
529	 -l --limit  limit number of changes displayed
530
531	use "hgtk -v help log" to show global options
532
533.. vim: noet ts=4