We are currently indexing your data, so search results may be incomplete until we finish.
stable doc: improve readability, add content. Part 2
Changeset 6394f8914483…
Parent 7a0ebe7e757c…
by
Changes to 2 files · Browse files at 6394f8914483 Showing diff from parent 7a0ebe7e757c Diff from another changeset...
|
|
|
@@ -11,11 +11,11 @@ `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).
+only component that defaults to the top level shell 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
@@ -25,59 +25,59 @@Features
--------
-Walking across the toolbar, the buttons perform the following tasks:
+Walking across the toolbar buttons:
-: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.
+ :guilabel:`Refresh`
+ Reload the state of the working directory. It tries to retain
+ check and selection state across refresh.
+ :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. If merging, it
+ allows you to select the revert parent.
+ :guilabel:`Add`
+ Add checked files that were in unknown '?' or ignored 'I' state.
+ :guilabel:`Move`
+ Move checked files to specified target directory in versioned
+ manner.
+ :guilabel:`Remove`
+ Delete checked unversioned files and/or remove (mark as deleted) any
+ versioned files.
-Below the toolbar are two other useful widgets:
+Below the toolbar are 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.
+ :guilabel:`Branch dialog`
+ Shows the current branch name of the working directory. Normally
+ this is informational only, but pressing this button opens up a
+ branch maintenance dialog. Do not use this feature unless you
+ understand Mercurial's
+ `named branches <http://mercurial.selenic.com/wiki/NamedBranches>`_.
+ :guilabel:`Recent Commit Messages`
+ A drop-down list of the 10 most recent commit messages. The
+ the drop-down list is filled the first time it is opened.
+ :guilabel:`QNew`
+ If you have enabled the MQ extension, there will also be a text
+ entry for a new patch name. Entering a patch name switches the
+ commit tool into 'QNew' mode.
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)
+ 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,
@@ -108,8 +108,8 @@on the command line.
-Change Selection (record)
--------------------------
+Change Selection
+----------------
So what does it mean when we say the commit button will commit the
selected diffs in checked files? Simple, the native TortoiseHg commit
@@ -122,12 +122,11 @@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.
+When you have more than a single coherent change in 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 is when this change selection feature becomes indespensable.
How does it work?
^^^^^^^^^^^^^^^^^
@@ -149,20 +148,18 @@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 short answer is that the selected hunks in checked files 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.
+the working copy). Files which are not partially selected avoid the
+entire *backup, revert, patch, commit, recover* round trip and instead
+are committed in place.
This longer answer is only interesting when something goes wrong, which
on Windows unfortunately has a probability greater than 0. If some
@@ -184,20 +181,20 @@ 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.
+diff headers. The clipboard contents will 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
+By right clicking on a file in the file list, you will get a context
+menu of commands that are applicable to the selected file. If multiple
+files are selected, the context menu only applies to the first selected
+file.
+
+If you have configured a visual editor (in
:menuselection:`Global Settings --> TortoiseHg --> Visual Editor`)
-there will be a menu option to open the file in your editor.
+this includes 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 is a copy or rename of a
@@ -206,8 +203,8 @@it).
-Merges
-------
+Merging
+-------
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
@@ -241,14 +238,22 @@may start the merge process again.
-Commit Message Format
----------------------
+Commit Message Pane
+-------------------
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.
+configure those in the settings tool. The commit tool will enforce this
+policy at commit time, and also has the ability to apply the policy to
+the current message.
+
+The commit message pane has special context menu options:
+
+ :guilabel:`Paste Filenames`:
+ Pastes checked filenames into the commit message at the cursor.
+ :guilabel:`Apply Format`:
+ Apply configured message wrap policy to current message.
+ :guilabel:`Configure Format`:
+ Opens the settings dialog to the :guilabel:`Commit` tab.
MQ patches
----------
@@ -314,7 +319,7 @@-------------
:menuselection:`Commit --> Username`
- Sets username associated with your commits
+ Sets username associated with your commits (see :doc:`quick`)
:menuselection:`Commit --> External Tool`
Allows you to select Qct as the your commit tool [DEPRECATED]
:menuselection:`Commit --> Summary Line Length`
@@ -331,35 +336,25 @@From command line
-----------------
-The commit tool can be started from command line ::
+The commit tool can be started from command line::
- hgtk commit
+ hgtk commit [OPTIONS] [FILE]...
-or ::
+ aliases: ci
- hgtk ci
+ commit tool
-The syntax is ::
+ options:
- hgtk commit [OPTIONS] [FILES]
+ -u --user record user as committer
+ -d --date record datecode as commit date
-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:
+ use "hgtk -v help commit" to show global options
-``-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::
+For a quick help on the format of date type::
- hgtk help dates
-
- or ::
-
- hg help dates
+ 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
-----------------
@@ -386,37 +381,4 @@* 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,5 +1,5 @@ - TortoiseHg Shelve Tool
-======================
+Shelve
+======
.. module:: shelve.dialog
:synopsis: Dialog used to perform shelve/unshelve operations
@@ -10,49 +10,58 @@ proper configuration. See
`issue #82 <http://bitbucket.org/tortoisehg/stable/issue/82/>`_.
+The purpose of this dialog is to allow the user to *shelve* selected changes
+from the working directory, store them in a special patch file within the
+repository, and then *unshelve* them back at a later time.
+
.. figure:: figures/shelve.png
:alt: Shelve dialog
Shelve dialog
-Visually it is very similar to the status dialog in 0.6 and the commit
-tool in 0.7. The purpose of this dialog is to allow the user to
-*shelve* selected changes from the working directory, store them in a
-special patch file in the repository, and then *unshelve* them back at a
-later time.
+Walking across the toolbar buttons:
-Walking across the toolbar, the buttons perform the following tasks:
+ :guilabel:`Refresh`
+ Reload the state of the working directory. It tries to retain
+ check and selection state across refresh.
+ :guilabel:`Shelve`
+ Shelve selected diffs in checked files.
+ :guilabel:`Unshelve`
+ Replace the shelved changes back into the working directory.
+ :guilabel:`Revert`
+ Revert checked files to last revisioned state. If merging, it
+ allows you to select the revert parent.
+ :guilabel:`Add`
+ Add checked files that were in unknown '?' or ignored 'I' state.
+ :guilabel:`Move`
+ Move checked files to specified target directory in versioned
+ manner.
+ :guilabel:`Remove`
+ Delete checked unversioned files and/or remove (mark as deleted) any
+ versioned files.
-:guilabel:`Refresh`
- Reload the state of the working directory. It retains file check and
- selection state across refresh, but not hunks.
-:guilabel:`Shelve`
- Shelve selected diffs in checked files.
-:guilabel:`Unshelve`
- Replace the shelved changes back into the working directory.
-: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.
-:guilabel:`Show Diff`
- This is a toggle button that shows and hides the entire diff panel.
- Hiding the diff panel can sometimes be useful in large repositories.
+The file list has four columns:
-Below the file list are checkboxes that toggle the inclusion of the
+ 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'.
+ 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}.
+clean, ignored}. These check boxes will be disabled if the commit tool
+was given a specific set of files and/or directories.
+
Shelving Changes
----------------
-
Just like the commit tool, this dialog uses TortoiseHg's integrated hunk
selection code to allow the user to select the files and change hunks to
move to the shelf. When you press the shelve button, the selected
@@ -61,9 +70,17 @@to replace those changes or to merge these new changes into it. When
the shelf has changes, the unshelve button will be active.
+
+Unshelving Changes
+------------------
+
When the unshelve button is pressed, the shelved changes are reapplied
to the working directory.
+.. note::
+ The unshelved changes will appear as working directory modifications
+ when the shelve tool refreshes it's view of the repository.
+
How is this different from record/commit?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -85,19 +102,30 @@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
-maintaining a patch queue, since it can hold changes from one patch and
-re-apply them to another patch (or an entirely new patch).
+The shelf can be considered a single unnamed MQ patch that is never
+converted into a changeset.
+
+The shelve tool can be useful when maintaining a patch queue.
+The shelf can take changes from one patch and re-apply them to another
+patch (or an entirely new patch).
+
+For example:
+ 1) Push to a patch you would like to split up
+ 2) Open the shelve tool, the top patch changes will be selectable
+ 3) Unselect change hunks you want to leave in the patch, then press
+ :guilabel:`Shelve`
+ 4) Refresh top patch using :command:`hg qrefresh`, or use commit tool
+ 5) Push or pop to the patch you want to apply shelved patches
+ 6) Open the shelve tool and press :guilabel:`Unshelve`
+ 7) Refresh top patch (repeat step 4)
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
-restored independently. TortoiseHg doesn't support the attic extension
-in 0.7, but will probably support attic like features in future
-releases.
+restored independently.
+
Keyboard navigation
-------------------
@@ -109,29 +137,27 @@ 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.
+diff headers. The clipboard contents will always be a valid patch.
+
Configurables
-------------
* :menuselection:`TortoiseHg --> Bottom Diffs`
* :menuselection:`TortoiseHg --> Tab Width`
+* :menuselection:`TortoiseHg --> Max Diff Size`
From command line
-----------------
-The shelve tool can be started from command line ::
+The shelve tool can be started from command line::
hgtk shelve
-or ::
+ aliases: unshelve
- hgtk unshelve
+ shelve/unshelve tool
-The syntax is simple, no options or parameters are needed, except the global options.
-
+ use "hgtk -v help shelve" to show global options
.. vim: noet ts=4
|
Add a tag
Loading...