/doc/source/workbench.txt

https://bitbucket.org/tortoisehg/hgtk/ · Plain Text · 533 lines · 449 code · 84 blank · 0 comment · 0 complexity · 93f6dca0918191ba2786d2678075c1a8 MD5 · raw file

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