We are currently indexing your data, so search results may be incomplete until we finish.
stable doc: fix section puntaction
Changeset 59979ef85be5…
Parent ef6a0a326d32…
by
Changes to 9 files · Browse files at 59979ef85be5 Showing diff from parent ef6a0a326d32 Diff from another changeset...
|
@@ -1,4 +1,3 @@ - ===========================
TortoiseHg Changelog Viewer
===========================
@@ -32,7 +31,7 @@This changelog browser offers much more.
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
@@ -51,7 +50,7 @@ load all remaining revisions into the graph
Revision Context Menus
-======================
+----------------------
Right-clicking on a revision in the (top) graph pane will bring up the
revision context menu.
@@ -114,7 +113,7 @@
File List Context Menus
-=======================
+-----------------------
Right-clicking on filenames in the file list (bottom left) pane will
bring up a context menu for the selected file:
@@ -139,7 +138,7 @@
Changeset browser
-=================
+-----------------
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
@@ -160,7 +159,7 @@accelerator to copy hightlighted diff hunks to the clipboard.
Configurables
-=============
+-------------
The changelog browser has a few configurable options that can be set in
the TortoiseHg Settings dialog on the Changelog tab.
@@ -192,7 +191,7 @@
From command line
-=================
+-----------------
The changelog viewer can be started from command line ::
|
||
|
|
|
- ======================
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.
Below the file list are checkboxes that toggle the inclusion of the
various classes of files {modified, added, removed, deleted, unknown,
clean, ignored}.
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.
Change Selection (record)
-=========================
+-------------------------
So what does that mean when it says 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).
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.
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.
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.
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.
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
|
|
@@ -1,4 +1,3 @@ - ===============
Common Features
===============
@@ -9,7 +8,7 @@here just once.
Geometry Restore
-================
+----------------
Our primary applications like commit, changelog, and datamine will
restore their geometry and position from the last time they were run.
@@ -22,7 +21,7 @@window manager to place them where it wishes.
Keyboard Accelerators
-=====================
+---------------------
We define a few keyboard accelerators that all of the TortoiseHg tools support.
@@ -47,7 +46,7 @@access cut-paste functionality, for instance.
Visual Diffs
-============
+------------
0.8 introduced a visual diff dialog that solves four usability issues:
@@ -61,7 +60,7 @@dialog and :menuselection:`TortoiseHg --> Skip Diff Window`.
Treeview searches
-=================
+-----------------
Many TortoiseHg dialogs use treeviews to present lists of data to the
user. The file lists in the status, commit, shelve, and changelog tools
@@ -82,7 +81,7 @@ matching lines
HG command dialog
-=================
+-----------------
Many TortoiseHg tools use the *hgcmd* dialog to execute Mercurial
commands that could potentially be interactive. In release 0.8, the
|
||
|
@@ -1,4 +1,3 @@ - ===================
TortoiseHg Datamine
===================
@@ -11,7 +10,7 @@
Search Tabs
-===========
+-----------
.. figure:: figures/search.png
:alt: Search dialog
@@ -55,7 +54,7 @@sensitive when a search is in progress).
Matches
-=======
+-------
Each match will be a link to a changeset and will have a descriptive
tooltip (author, date/time, summary). Right clicking on a matched line
@@ -69,7 +68,7 @@ open a changelog window with this file's revision history
Annotate Tabs
-=============
+-------------
.. figure:: figures/annotate.png
:alt: Annotate tabs
@@ -94,7 +93,7 @@:guilabel:`filename` and :guilabel:`user`.
Following Renames
------------------
+^^^^^^^^^^^^^^^^^
The annotation data will automatically follow lines of code back through
copies and renames to find the initial changeset that introduced that
@@ -106,7 +105,7 @@annotated at the same changeset.
Configurables
--------------
+^^^^^^^^^^^^^
The annotate tabs support the following configurations defined primarily
for other tools:
@@ -117,7 +116,7 @@ Number of spaces to expand tabs in diffs and annotate output
From command line
-=================
+-----------------
The datamine tool can be started from command line ::
|
||
|
@@ -1,12 +1,11 @@ - ============================
Windows Explorer Integration
-============================
+----------------------------
.. module:: explorer
:synopsis: Windows explorer integration
Overlay Icons
-=============
+-------------
TortoiseHg provides visual representation of the file status via overlay
icons in the MS-Explorer windows. This is similar to those that found on
@@ -35,7 +34,7 @@ @@noicons
Performance Issues
-==================
+------------------
When the repository being viewed contains a large number of folders or
files, the overlay icons may appear case a perceivable delay in
@@ -55,7 +54,7 @@local disks only.
Context Menus
-=============
+-------------
The TortoiseHg commands (GUI window & dialogs) may be accessed via the
context menu of Explorer windows. The TortoiseHg context menu is
|
||
|
|
||
|
@@ -1,4 +1,3 @@ - ================
TortoiseHg Serve
================
@@ -47,7 +46,7 @@shell context menu.
From command line
-=================
+-----------------
The server tool can be started from command line ::
@@ -65,7 +64,7 @@
Changes since 0.7
-=================
+-----------------
* Improved error handling
* i18n fixes
|
||
|
@@ -1,4 +1,3 @@ - ======================
TortoiseHg Shelve Tool
======================
@@ -51,7 +50,7 @@clean, ignored}.
Shelving Changes
-================
+----------------
Just like the commit tool, this dialog uses TortoiseHg's integrated hunk
@@ -66,7 +65,7 @@to the working directory.
How is this different from record/commit?
------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Shelved changes are physically removed from the working directory until
you unshelve them. This means you can build your project and run tests
@@ -84,7 +83,7 @@changes made to your code after the shelving.
How is this different from MQ?
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A shelf is, in effect, a single unnamed MQ patch that is never converted
into a changeset. The shelve tool can be useful when you are
@@ -92,7 +91,7 @@re-apply them to another patch (or an entirely new patch).
How is this different from attic?
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The attic extension is a super-set of the shelve feature. In particular,
attic allows you to have several named *shelves* which can be saved and
@@ -101,7 +100,7 @@releases.
Keyboard navigation
-===================
+-------------------
:guilabel:`Ctrl-C`
in the diff panel will copy the currently highlighted (not selected,
@@ -116,13 +115,13 @@clipboard contents always be a valid patch.
Configurables
-=============
+-------------
* :menuselection:`TortoiseHg --> Bottom Diffs`
* :menuselection:`TortoiseHg --> Tab Width`
From command line
-=================
+-----------------
The shelve tool can be started from command line ::
|
||
|
@@ -1,4 +1,3 @@ - ======================
TortoiseHg Synchronize
======================
@@ -96,7 +95,7 @@
After Pull
-==========
+----------
After changesets are pulled into your repository, two buttons may appear
at the bottom of the dialog:
@@ -109,7 +108,7 @@Either button may be hidden if it is not applicable.
Email
-=====
+-----
.. figure:: figures//email.png
:alt: Email dialog
@@ -137,7 +136,7 @@plain patches, HG patches, Git patches, and bundles.
From command line
-=================
+-----------------
The synchronize tool can be started from command line ::
@@ -171,7 +170,7 @@path it finds.
Changes since 0.7
-=================
+-----------------
* Path drop-down list no longer includes most-recently-used paths. It
only includes configured repository paths.
|
||
Add a tag
Loading...