/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
- Changelog
- =========
- .. module:: changelog.dialog
- :synopsis: Dialog used to view log
- The changelog tool (*also known as the repository explorer*) is
- used to visualize the revision history of your repository and to perform
- any maintenence tasks that involve changesets. It presents a graph of
- the revision history, showing the parent/child relationship of each
- change. At each revision you can view the files that were modified and
- the contents of those changes.
- .. figure:: figures/log.png
- :alt: Changelog
- Changelog viewer dialog with main toolbar hidden
- The changelog tool has a menu bar for accessing tool functions and for
- launching other tools.
- :guilabel:`Tools`
- Launch other TortoiseHg tools as separate processes
- :guilabel:`View`
- Toggle the visibility of various features, or refresh views
- :guilabel:`Navigate`
- Select specific changesets in your repository history
- :guilabel:`Synchronize`
- Access synchronization functions, more below
- :guilabel:`Help`
- Help contents shows this web page. About shows TortoiseHg
- version info
- The toolbar buttons from left to right:
- :guilabel:`Refresh`
- Reload the revision history (if you commit in another window, etc)
- :guilabel:`Reset Marks`
- Remove 'new', 'incoming', and 'outgoing' revision marks and refresh
- :guilabel:`Patch Queue`
- Toggles the display of the MQ pane. This button is only visible
- when the MQ extension has been enabled by the user.
- :guilabel:`Commit`
- Launch the commit tool in a separate process
- :guilabel:`Datamine`
- Launch the data mining tool in a separate process
- :guilabel:`Recovery`
- Launch the recovery dialog in a separate process
- :guilabel:`Web Server`
- Launch the web server dialog in a separate process
- :guilabel:`Shelve`
- Launch the shelve tool in a separate process
- :guilabel:`Patch Branch`
- Toggles the display of the Patch Branch pane. This button is only
- visible when the pbranch extension has been enabled by the user.
- :guilabel:`Load more`
- Load the next N revisions into the graph
- :guilabel:`Load all`
- Load all remaining revisions into the graph
- Sync Bar
- ---------
- .. figure:: figures/syncbar.png
- :alt: Changelog
- Synchronization features in changelog tool
- From left to right...
- :guilabel:`Incoming`
- Download incoming changesets from the remote repository, store
- them in a temporary bundle file, then enter bundle preview mode
- with the incoming changes applied. Incoming changesets will
- have a 'down' arrow in the revision graph.
- :guilabel:`Accept`
- Accept (pull) the changesets from the previewed bundle. This
- button is only sensitive when previewing a changeset bundle.
- The after-pull effect is respected after pulling from a bundle.
- :guilabel:`Reject`
- Reject the changesets from the previewed bundle and exit preview
- mode. This button is only sensitive when previewing a changeset
- bundle.
- :guilabel:`Pull`
- Pull incoming changesets from the remote repository, then apply
- after-pull effect (update, fetch, or rebase).
- :guilabel:`Import`
- Open the import dialog to import one or more patches
- :guilabel:`Outgoing`
- Determine outgoing changesets that would be pushed to the
- remote repository. Outgoing changesets are marked with an 'up'
- arrow.
- :guilabel:`Push`
- Push outgoing changesets to the remote repository.
- :guilabel:`Email`
- Email outgoing changesets to the remote repository.
- :guilabel:`Stop`
- Stop current transaction. The button is only sensitive during
- outgoing commands.
- To the right of the :guilabel:`Stop` button is a combo box containing
- all of the configured peer repository paths for the current repository.
- The default path is selected at startup, if it has been configured.
- See `hg.1.html#urls <http://www.selenic.com/mercurial/hg.1.html#urls>`_ for
- details on specifying remote repository URLs.
- To the right of the path combo box is the :guilabel:`After Pull` combo
- that selects the operation which is performed after every pull operation
- triggered by the sync bar. The user must have the rebase extension
- enabled in order for that option to be available in the after pull
- combo. The same is true of the fetch extension and it's post pull
- operation.
- To the right of the :guilabel:`After Pull` combo is the
- :guilabel:`Settings` button. It opens the repository settings tool on
- the :guilabel:`Sync` tab where the after pull configurable and peer
- repository paths can be configured.
- Changesets which are added to the repository after the changelog tool
- was opened are marked with green stars in the graph. This includes
- recent commits, pulled changesets, and applied patches.
- .. note::
- To clear the new, incoming, and outgoing marks from the changeset
- graph, use :guilabel:`View -> Reset Marks`
- Search Bar
- ----------
- .. figure:: figures/searchbar.png
- :alt: Changelog
- Filter features in changelog tool
- The search bar allows one to quickly filter the changesets panel.
- Buttons from right to left...
- :guilabel:`All`
- Show all changesets in the respository. Essentially removes all
- filters.
- :guilabel:`Tagged`
- Show only changesets with tags.
- :guilabel:`Ancestry`
- Show only changesets that are ancestors of the currently
- selected changeset. This option is only sensitive when a
- revision is selected.
- :guilabel:`Parents`
- Show only the working directory parent revisions. Unless a
- merge is in progress, this will be only one revision.
- :guilabel:`Heads`
- Show only repository heads (changesets without any child
- revisions).
- :guilabel:`Merges`
- Show only merge changesets (changesets with two parents)
- :guilabel:`Hide Merges`
- A toggle button, not a radio like the other buttons in the
- search bar, which toggles the display of merge changesets.
- :guilabel:`Branches`
- A combo box with the list of named branches in your repository.
- See :guilabel:`Repo Settings -> Changelog -> Dead Branches` for
- a method to prune names from this combo box.
- :guilabel:`Custom Filter Combo`
- Finally there is a combo box that selects among the various
- filter types that can be manually specified.
- To specify a custom filter, the user selects the filter type, enters
- the search text of that type, and then hits return in the text entry.
- :guilabel:`Revision Set`
- Parse the user text as a revision set. See
- `hg.1.html#revisions <http://www.selenic.com/mercurial/hg.1.html#revsets>`_
- for details on how to specify revision sets.
- :guilabel:`File Patterns`
- Parse the user text as a file pattern glob, unless the user text
- is prefixed with a pattern type like *regexp:*. See
- `hg.1.html#patterns <http://www.selenic.com/mercurial/hg.1.html#patterns>`_
- for details on how to specify file patterns.
- :guilabel:`Keywords`
- Parse the user text as a keyword pattern that should be matched
- against changeset meta data like comitter, message, etc.
- :guilabel:`Date`
- Parse the user text as a date range. See
- `hg.1.html#dates <http://www.selenic.com/mercurial/hg.1.html#dates>`_
- for details on how to specify date ranges.
- :guilabel:`User`
- Parse the user text as a user / comitter name.
- The filter entry has a combo box which stores the history of searches.
- Selecting an item from the drop down list will apply that filter.
- Revision Graph Details
- ----------------------
- The graph column shows the child-parent relationships between revisions
- in your repository history. This column auto-sizes for as many lines of
- ancestry that are required to visualize the revisions you have loaded.
- The column has an initial hard-limit width to prevent some degenerative
- cases from breaking the viewer, but can be resized after refreshes.
- Performance Implications
- ------------------------
- There are some Repository Explorer features that should probably be
- avoided in large repositories.
- * :menuselection:`View -> Color By Branch`
- This option requires the log viewer to query the branch name of
- every revision in order to draw the graph. It can cause refreshes
- to be slow.
- * :menuselection:`View -> Compact Graph`
- This option can cause refresh to be slower than the default setting.
- Also be aware that enabling this feature makes the graph lines less
- accurate. The feature trades merge parent accuracy for horizontal
- screen space.
- * Column :guilabel:`Changes`
- This column can be expensive to calculate on repositories with large
- working copies, causing both refreshes and scrolling to be slow.
- Revision Context Menus
- ----------------------
- Right-clicking on a revision in the (top) graph pane will bring up the
- revision context menu.
- :guilabel:`Visualize Change`
- Open this change in your visual diff tool
- :guilabel:`Display Change`
- Open this changeset in the changeset browser (more below)
- :guilabel:`Diff to Local`
- Display changes (visual diff) between this revision and your
- current working directory
- :guilabel:`Copy Hash`
- Copy current revision's full hash to the clipboard
- :guilabel:`Push to Here`
- Performs the equivalent of 'push -r <rev>'. This option is only
- available on changesets marked as outgoing.
- :guilabel:`Push this Branch`
- Performs the equivalent of 'push --new-branch --branch <branch>'.
- This option is only available on changesets marked as outgoing.
- :guilabel:`Update...`
- Update your working directory to this revision. Opens the
- TortoiseHg update dialog with this revision selected.
- :guilabel:`Merge With...`
- Merge with this revision. Opens the TortoiseHg merge dialog with
- this revision selected.
- :guilabel:`Backout...`
- Create a backout changeset for selected revision
- :guilabel:`Revert`
- Revert working copy to this revision's contents, without
- updating working directory parent revision. Use with care.
- :guilabel:`Export`
- :guilabel:`Export Patch`
- Generate a patch file containing this revision's changes
- :guilabel:`Email Patch`
- Send this revision's changes to email recipient. Opens the
- TortoiseHg email dialog with this revision selected.
- :guilabel:`Bundle rev:tip`
- Create a bundle with all revs from selected to tip
- :guilabel:`Archive...`
- Open the archive dialog for this revision, allowing user to
- generate a backup copy of the repository at that revision.
- :guilabel:`Tag`
- :guilabel:`Add/Remove Tag`
- Open the TortoiseHg tag dialog with this revision selected
- :guilabel:`Add/Move/Remove Bookmark`
- Open the TortoiseHg bookmark dialog with this revision selected
- *This option requires the boomarks extension to be enabled*
- :guilabel:`Rename Bookmark`
- Open the TortoiseHg bookmark rename dialog
- *This option requires the boomarks extension to be enabled*
- :guilabel:`Mercurial Queues`
- :guilabel:`Import revision to MQ`
- Import selected revision into the current patch queue. Only
- valid for qbase or checked out head revision. *Only visible
- when MQ is enabled*
- :guilabel:`Strip Revision...`
- Remove the selected revision and all of it's descendants from the
- repository [#rcm1]_ *Only visible when MQ is enabled*
- :guilabel:`Transplant to local`
- Transplant selected revision onto the current working parent.
- *Only visible when the transplant extension is enabled*
- :guilabel:`Bisect`
- :guilabel:`Reset`
- Reset bisect state. See `bisect <#id10>`_ section below.
- :guilabel:`Mark as Good`
- Mark changeset as good
- :guilabel:`Mark as Bad`
- Mark changeset as bad
- :guilabel:`Skip Testing`
- Skip testing this changeset
- If you right-click on a row other than the one that was currently
- selected, you get a secondary context menu which defines commands that
- operation on revision ranges.
- :guilabel:`Diff with selected`
- Opens status viewer with cumulative changes of the range of
- changesets. The status viewer allows cherry picked changes to
- be saved to a file.
- :guilabel:`Visual Diff with selected`
- Opens visual diff window with cumulative changes of the range
- of changesets. See also menuselection:`Global Settings -->
- TortoiseHg --> Visual Diff Tool`
- :guilabel:`Email from here to selected`
- Opens email dialog with range of changesets.
- :guilabel:`Bundle from here to selected`
- Creates a bundle file with range of changesets.
- :guilabel:`Export patches from here to selected`
- Creates a patch file for each changeset in selected range.
- :guilabel:`Merge with ...`
- Merges this revision with the other selected revision. If
- neither revision is currently checked out, the merge dialog will
- be forced to update to the first selected revision before
- starting the merge. This will fail if the working directory is
- not clean.
- :guilabel:`Transplant revision range to local`
- Transplant selected range of changesets on to current working
- parent revision. *Only visible when the transplant extension is
- enabled*
- :guilabel:`Rebase on top of selected`
- Rebase selected changeset and ancestors on top of original
- selected revision. *Only visible when the rebase extension is
- enabled*
- :guilabel:`Import from here to selected to MQ`
- Import selected revision range into the current patch queue.
- *Only visible when MQ is enabled*
- :guilabel:`Select common ancestor`
- Selects (highlights) the common ancestor of the two selected
- revisions. Helpful, when reviewing merges.
- .. [#rcm1] The strip command will store the stripped revisions in a bundle file
- that can later be reapplied.
- See also `EditingHistory <http://mercurial.selenic.com/wiki/EditingHistory>`_.
- File Context Menus
- ------------------
- Right-clicking on filenames in the file list (bottom left) pane will
- bring up a context menu for the selected file:
- :guilabel:`Visual Diff`
- Open this revision of the file in your visual diff tool
- :guilabel:`Diff to Local`
- Visualize differences between this revision and your checked
- out version
- :guilabel:`View at Revision`
- Open this revision of the file in your visual editor [#flcm1]_
- :guilabel:`Save at Revision`
- Write this revision of the file to specified location
- :guilabel:`File History`
- Show revisions that modified this file [#flcm2]_
- :guilabel:`Annotate File`
- Open this file in the datamine app, annotated at this revision
- :guilabel:`Revert File Contents`
- Checkout this specific revision of this file [#flcm3]_
-
- .. [#flcm1] :menuselection:`Global Settings --> TortoiseHg --> Visual Editor`
- .. [#flcm2] Does not show revisions where a file was deleted, as this is only a
- manifest change, it does not modify the file's history.
- .. [#flcm3] The new contents will appear as local changes and must be committed.
- Changeset browser
- -----------------
- The changeset browser will only show a single file's diffs at a time, as
- a performance optimization. If you would like to see all of the file
- diffs at once, click on the :guilabel:`[All Files]` row. The changeset
- browser will also skip displaying diffs for files which are above a
- maximum limit. See
- :menuselection:`Global Settings --> TortoiseHg --> Max Diff Size`. The
- size limit can be temporarily disabled by toggling :menuselection:`View
- -> Ignore Max Diff Size`.
- The changelog and datamine tools can open the changeset browser to view
- a single revision or the combined effect of a range of revisions. The
- changeset browser is very similar to the commit and shelve tools. It has
- a file list on the left of all files that have been changed, and a diff
- pane on the right with the changes to each file.
- The diff pane is tabbed and allows one to select files and hunks that
- you wish to extract from the changeset(s) you are browsing and write
- them to a patch file using the :guilabel:`Save as` toolbar button. This
- is a very efficient way to cherry pick changes from a repository. This
- changeset browser also supports the :kbd:`Ctrl-C` keyboard accelerator
- to copy hightlighted diff hunks to the clipboard.
- Unfortunately, TortoiseHg still does not have a dialog for importing
- patches into a repository, so this must be done on the command line with
- the :command:`hg import` command.
- Message Parsing
- ---------------
- New in TortoiseHg 1.0, the repository browser will detect and underline
- changeset hashes, HTTP(s) URLs, and bug report identifiers inside
- changeset messages. These underlined phrases are clickable links.
- Every word-boundary delimited string of 12 or 40 characters from the
- range [0-9a-f] is considered a changeset link. Clicking on it in the
- repository explorer will jump to the given changeset if possible.
- HTTP and HTTPS URLs are similarly turned into clickable links which are
- opened in your default web browser.
- Issue tracker links are enabled when configured in the tortoisehg
- section of your configuration files. Since only a single issue tracker
- can be configured at a time, it is typically configured in the
- repository's :file:`.hg/hgrc` file. There are two keys: issue.regex and
- issue.link. The first defines the regex to match when picking up issue
- numbers, while the second defines the command to run when an issue
- number is recognized.
- You may include groups in issue.regex, and corresponding {n} tokens in
- issue.link (where n is a non-negative integer). {0} refers to the entire
- string matched by issue.regex, while {1} refers to the first group and
- so on. If no {n} tokens are found in issue.link, the entire matched
- string is appended instead.
- Examples::
- BitBucket:
- issue.regex = #(\d+)\b
- issue.link = http://bitbucket.org/<your project and repo>/issue/{1}/
- Mercurial:
- issue.regex = \bissue\d+\b
- issue.link = http://mercurial.selenic.com/bts/
- Bisect
- ------
- TortoiseHg 1.0 introduced support for bisect bug searching to help find
- changesets which introduce problems. To use, mark the earliest changeset
- you know exhibits the problem as bad, then mark the latest changeset
- which is free from the problem as good. The changelog tool will select
- a changeset for you to test. Once you have performed tests, mark the
- changeset as good or bad, and bisect will either update to another
- candidate changeset or announce that it has found the bad revision.
- As a shortcut, you can also mark a revision as good or bad without
- checking it out first.
- For more automated bisecting, you must use the Mercurial command line
- and provide an automated test that can build and run a changeset and
- return 0-good, 125-skip, or 127-abort, or anything else to mean bad.
- See the :command:`hg bisect` command help for more information.
- Keyboard navigation
- -------------------
- :kbd:`Ctrl-P`
- Zoom to the working directory parent revision
- :kbd:`Ctrl-D`
- Display visual diffs for selected changeset or file
- :kbd:`Ctrl-R`
- Refresh repository contents
- :kbd:`Ctrl-G`
- Go to a specific revision
- Configurables
- -------------
- The changelog browser has a few configurable options that can be set in
- the TortoiseHg Settings dialog on the Changelog tab.
- :guilabel:`Author coloring`
- If true, each author's changeset will be given a unique color
- :guilabel:`Long Summary`
- Concatenate commit message lines until 80 chars are reached
- :guilabel:`Graph batch limit`
- Number of revisions to read in each batch load
- :guilabel:`Copy Hash`
- Copy a revision's changeset id hash to the clipboard when selected
- [DEPRECATED]
- :guilabel:`Dead Branches`
- Comma separated list of branch names that should be ignored
- when building a list of branch names for a repository.
- :guilabel:`Branch Colors`
- Space separated list of branch names and colors on the
- form branch:#XXXXXX. Spaces and colons in the branch name must be
- escaped using a backslash (\\). Likewise some other characters
- can be escaped in this way, e.g. \\u0040 will be decoded to the
- @ character, and \\n to a linefeed.
- :guilabel:`Hide Tags`
- Space separated list of tags that will not be shown. Useful
- example: Specify "qbase qparent qtip" to hide the standard tags
- inserted by the Mercurial Queues Extension.
- :guilabel:`Use Expander`
- Show changeset details within an expander. When contained
- within the expander, the details do not scroll with the
- changeset contents.
- The exact colors given to particular users can be configured by adding
- lines like these to your :file:`Mercurial.ini` file: ::
- [tortoisehg]
- authorcolor.USERNAME = color
- The changelog browser also respects the following settings on the
- TortoiseHg tab:
- :guilabel:`Tab Width`
- Number of spaces to expand tabs in diffs
- :guilabel:`Max Diff Size`
- Maximum size of file to be diffed
- :guilabel:`Bottom Diffs`
- Show diffs below file list
- From command line
- -----------------
- The changelog viewer can be started from command line ::
- hgtk log [OPTIONS] [FILE]
- aliases: history
- changelog viewer
- options:
- -l --limit limit number of changes displayed
- use "hgtk -v help log" to show global options
- .. vim: noet ts=4