Changeset bb873cca2bab…
Parent df783202e98c…
by
Changes to 27 files · Browse files at bb873cca2bab Showing diff from parent df783202e98c Diff from another changeset...
|
@@ -0,0 +1,75 @@ + # Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview over all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+
+clean:
+ -rm -rf build/*
+
+html:
+ mkdir -p build/html build/doctrees
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
+ @echo
+ @echo "Build finished. The HTML pages are in build/html."
+
+pickle:
+ mkdir -p build/pickle build/doctrees
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+web: pickle
+
+json:
+ mkdir -p build/json build/doctrees
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ mkdir -p build/htmlhelp build/doctrees
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in build/htmlhelp."
+
+latex:
+ mkdir -p build/latex build/doctrees
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in build/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ mkdir -p build/changes build/doctrees
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
+ @echo
+ @echo "The overview file is in build/changes."
+
+linkcheck:
+ mkdir -p build/linkcheck build/doctrees
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in build/linkcheck/output.txt."
|
|
@@ -0,0 +1,20 @@ + TortoiseHg Documentation
+
+To build this documentation you need sphinx installed. On Ubuntu this
+is the python-sphinx package. On Windows your best bet is
+easy_install.
+
+To build PDF files you need the texlive packages. On Ubuntu this is
+texlive-latex-extra and all of it's dependencies.
+
+On Windows, you also need a make tool. MinGW of GnuWin32 are
+recommended.
+
+Once all of the prerequisites are in place, you use the makefile to
+build targets: html htmlhelp latex
+
+Once latex is built, you have to cd into that output directory and run
+make all-pdf to build the actual PDF file.
+
+Once htmlhelp is built, you have to run the actual help compiler on a
+Windows machine.
|
|
@@ -0,0 +1,6 @@ + Needs an Intro page explaining TortoiseHg and it's ports. Include links
+Changelog needs much more detail
+Commit needs more detail, including ignore and guess dialogs
+Add links to BB wiki and Mercurial wiki
+Describe path editing and [auth] hgrc section
+Need a page explaining merges and merge undo
|
|
|
@@ -0,0 +1,179 @@ + ===========================
+TortoiseHg Changelog Viewer
+===========================
+
+.. figure:: figures/log.png
+ :alt: Changelog
+
+ Changelog viewer dialog
+
+The toolbar buttons from left to right:
+
+*Refresh*
+ Reload the revision history (if you commit in another window, etc)
+*Filter*
+ Open revision filter dialog, also has drop-down for common filters
+*Datamine*
+ Open datamine application for history searches and file annotations
+*Other Parent*
+ Only active when viewing merge changesets, toggles parents
+*Synchronize*
+ Communicate changes with other repositories
+
+The changelog tool is primarily used to visualize the revision history
+of your repository. 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 it modified and the contents of those changes. These
+are the obvious features that a revision history browser provides.
+
+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
+ancestry that are required to visualize the revisions you have loaded.
+The column does have a hard-limit width to prevent some degenerative
+cases from breaking the viewer.
+
+On the right of the revision graph are three buttons. From top to bottom
+these are:
+
+*column toggles*
+ toggle the display of columns in the graph
+*next-N revisions*
+ load the next N revisions into the graph
+*all revisions*
+ 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.
+
+*visualize change*
+ open this change in your visual diff tool
+*display change*
+ open this changeset in the changeset browser (more below)
+*diff to local*
+ display changes (visual diff) between this revision and your current working directory
+*update*
+ update your working directory to this revision [1]
+*merge with*
+ merge with this revision [2]
+*copy hash*
+ copy current revision's full hash to the clipboard
+*export patch*
+ generate a patch file of this revision's changes
+*email patch*
+ send this revision's changes to email recipient [3]
+*bundle rev:tip*
+ create a bundle with all revs from selected to tip
+*add/remove tag*
+ opens the TortoiseHg tag dialog with this revision selected
+*backout*
+ create a backout changeset for selected revision
+*revert*
+ revert working copy to this revision's contents, without updating working
+ directory parent revision. Use with care.
+*strip*
+ Remove the selected revision and all of it's descendants from the repository [4]
+
+
+If you right-click on a row other than the one that was currently selected, you get a different context menu. This one is for visualizing diffs between two arbitrary revisions.
+
+*diff with selected*
+ Description
+*visual diff with selected* [5]
+ Description
+*email from here to selected*
+ Description
+*bundle from here to selected*
+ Description
+*merge with selected* [6]
+ Description
+
+1) Opens the TortoiseHg update/checkout dialog with this revision selected.
+2) Opens the TortoiseHg merge dialog with this revision selected.
+3) Opens the TortoiseHg email dialog with this revision selected.
+4) The strip command will store the stripped revisions in a bundle file that can later be reapplied. See also_
+5) *Settings->Global->TortoiseHg->Visual Diff Command*
+6) Only sensitive if the selected revision is your current working directory parent
+
+.. _also: http://www.selenic.com/mercurial/wiki/index.cgi/EditingHistory
+
+
+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:
+
+*visual diff*
+ Open this revision of the file in your visual editor[1]
+*diff to local*
+ Visualize differences between this revision and your checked out version
+*save at revision*
+ Write this revision of the file to specified location
+*file history*
+ Show revisions that modified this file [2]
+*annotate file*
+ Open this file in the datamine app, annotated at this revision
+*revert file contents*
+ Checkout this specific revision of this file [3]
+
+1) Settings->Global->TortoiseHg->Visual Editor
+2) Does not show revisions where a file was deleted, as this is only a manifest change, it does not modify the file's history.
+3) The new contents will appear as local changes and must be committed.
+
+
+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
+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.
+
+In release 0.7 of TortoiseHg, the 'diff change with' changeset browser
+now supports change selection. You can 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 *Save as* toolbar button. This is a very
+efficient way to cherry pick changes made to a repository.
+Unfortunately, TortoiseHg still does not have a dialog for importing
+changes into a repository, so this must be done on the command line with
+the ``hg import`` command.
+
+This changeset browser also supports the *CTRL-C* keyboard 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.
+
+*Author coloring*
+ If true, each author's changeset will be given a unique color
+*Long Summary*
+ Concatenate commit message lines until 80 chars are reached
+*Graph batch limit*
+ Number of revisions to read in each batch load
+*Copy Hash*
+ Copy a revision's changeset id hash to the clipboard when selected
+
+The exact colors given to particular users can be configured by adding lines like these to your ``Mercurial.ini`` file: ::
+
+ [tortoisehg]
+ authorcolor.USERNAME = color
+
+The changelog browser also respects the following settings on the TortoiseHg tab:
+
+*Tab Width*
+ Number of spaces to expand tabs in diffs
+*Max Diff Size*
+ Maximum size of file to be diffed
+*Bottom Diffs*
+ Show diffs below file list
|
|
|
@@ -0,0 +1,323 @@ + ======================
+TortoiseHg Commit Tool
+======================
+
+This page describes the 0.8 version of commit
+
+**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.**
+
+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:
+
+*Refresh*
+ Reload the state of the working directory. It tries to retain file
+ check and selection state across refresh, but not hunks.
+*Commit*
+ Commit selected diffs in checked files.
+*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.
+*Revert*
+ Revert checked files to last revisioned state.
+*Add*
+ Add checked files that were in unknown '?' state. These files will
+ then be versioned as soon as they are committed.
+*Move*
+ Move checked files to specified target directory. This move is done
+ with Mercurial's full knowledge.
+*Remove*
+ Delete checked unversioned files and/or remove (mark as deleted) any
+ versioned files.
+
+Below the toolbar are two other useful widgets:
+
+*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.
+*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.
+*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
+simply 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, simply delete any new .rej files and try the commit again.
+
+
+
+Keyboard navigation
+-------------------
+
+*CTRL-ENTER*
+ will trigger the commit
+*CTRL-W*
+ will close the top dialog window
+*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 *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 *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 ``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 *commit* button, which has been renamed *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 ``hgtk ci`` to refresh your
+patches and take advantage of our excellent change selection support.
+
+
+Configurables
+-------------
+
+*Commit->Username*
+ Sets username associated with your commits
+*Commit->External Tool*
+ Allows you to select Qct as the your commit tool
+*Commit->Summary Line Length*
+ Configures a 'policy' limit for summary lines
+*Commit->Message Line Length*
+ Configures a 'policy' limit for message lines
+*Commit->Bottom Diffs*
+ Toggles diff pane from left to below file list
+*TortoiseHg->Max Diff Size*
+ Configures the diff size limit
+
+Changes from 0.6 to 0.7
+-----------------------
+
+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_ 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.
+
+.. _FAQ: http://bitbucket.org/tortoisehg/stable/wiki/FAQ#tortoisehg-faq
+
+
+The default layout of the native commit tool is different than Qct. The
+file list is on the left side of the diff panel. This layout is actually
+configurable if you prefer the Qct layout, simply set the
+*Commit->Bottom Diffs* configuration item to ``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 ``hg commit``
+command with no arguments. Similarly, unknown **?** files are shown by
+default at startup since that is standard behaviour for the ``hg
+status`` command. Qct was already doing both of these things, so this
+will come as no surprise to Qct users.
+
+
+Changes from 0.7 to 0.8
+-----------------------
+
+* The *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.
+* *Ctrl-O* keyboard accelerator for triggering commit has been replaced with
+ *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 simply show a message
+ indicating why the file was not diffed. This limit (default: 1MB) is
+ configurable (per-repository if necessary) via the settings dialog
+ TortoiseHg->Max Diff Size.
+* You can specify the commiter and date via the command line: see ``hgtk
+ commit -h`` for details
+* The ``qct.py`` extension file is no longer bundled. It must be
+ downloaded separately if you wish to use Qct.
+
+
+External tool configuration is deprecated and will be removed in 0.9
+
|
|
@@ -0,0 +1,81 @@ + ===============
+Common Features
+===============
+
+These features are commonly available in many TortoiseHg tools, so we
+document them 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.
+This includes maximization.
+
+If the state to be restored does not fit within your current screen
+dimensions, the application will revert to factory default dimensions.
+
+The TortoiseHg dialogs which are more transitory in nature (clone, init,
+synch, update, merge) simply allow the window manager to place them
+where it wishes.
+
+Keyboard Accelerators
+---------------------
+
+We define a few keyboard accelerators that all of the TortoiseHg tools support.
+
+*CTRL-Q*
+ quit the application, including all open windows
+
+*CTRL-W*
+ close the current window (same as *CTRL-Q* if only one window is open)
+
+*CTRL-D*
+ visual diff of currently selected file or changeset
+
+*CTRL-ENTER*
+ activation
+
+*F5*
+ refresh
+
+On `Mac OS X`_, the apple (command) key is used as the modifier instead
+of *CTRL*. However some keyboard accelerators are internal to GTK+ so
+you must use the control key to access cut-paste functionality, for
+instance.
+
+.. _`Mac OS X`: http://bitbucket.org/tortoisehg/stable/wiki/MacOSX
+
+Visual Diffs
+------------
+
+0.8 introduced a visual diff dialog that solves four usability issues:
+
+1) The ability to select visual diff tools for individual files
+2) Allows you to use visual diff tools that fork backround processes
+3) Allows you to use visual diff tools that do not support directory diffs
+4) Provides feedback when no files were modified
+
+If you prefer the previous (<=0.7) behavior of directly launching your
+visual diff tool, then you can recover that behavior via the user
+settings dialog and *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
+are treeviews. The changelog graph pane is a treeview. And even the
+annotate pane in the datamine tool is a treeview.
+
+Most of the TortoiseHg treeviews (as of release 0.8) are configured for
+live searches. You simply ensure that the treeview has focus (by
+clicking on a row), then begin typing. A small entry window will appear
+with the text you have typed and the treeview will immediately jump to
+the first row that matches the text you have entered thus far. As you
+enter more keys, it refines it's search.
+
+* *CTRL-F* will bring up the search window explicitly
+* *CTRL-G* will advance the search to the next match,
+* *SHIFT-CTRL-G* goes backwards
+* The mouse scroll wheel will advance forwards and backwards through matching lines
|
|
|
@@ -0,0 +1,190 @@ + # -*- coding: utf-8 -*-
+#
+# TortoiseHg documentation build configuration file, created by
+# sphinx-quickstart on Tue Jul 21 23:42:44 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If your extensions (or modules documented by autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'TortoiseHg'
+copyright = u'2009, Steve Borho and others'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.8'
+# The full version, including alpha/beta/rc tags.
+release = '0.8.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'TortoiseHgdoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', 'TortoiseHg.tex', ur'TortoiseHg Documentation',
+ ur'Steve Borho and others', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
|
|
|
@@ -0,0 +1,103 @@ + ===================
+TortoiseHg Datamine
+===================
+
+This page describes the 0.7 version of datamine
+
+The datamine application is used to inspect the revision history of your
+repository. It is a tabbed application that supports two tab types,
+shown below.
+
+
+Search Tabs
+-----------
+
+.. figure:: figures/search.png
+ :alt: Search dialog
+
+ Search dialog
+
+The search tab is used to search (*grep*) through your entire revision
+history for keywords, variable names, functions, etc...
+
+The text entry fields have these purposes:
+
+*regexp*
+ this is where you enter your regular expression search criteria.
+*includes*
+ a comma separated list of paths to include in your search. If no
+ paths are given, the search is assumed to be repository wide. In
+ other words, specifying an include path actually narrows the search
+ criteria.
+*excludes*
+ a comma separated list of paths to exclude from your search.
+ Exclusion patterns are applied after inclusion patterns.
+
+The toggle buttons below the entry fields are for:
+
+*Follow copies and renames*
+ follow searches through copies and renames out of inclusion filters
+*Ignore case*
+ Perform the search without case considerations
+*Show line numbers*
+ Show line numbers at the front of the matching lines
+*Show all matching revisions*
+ Show every instance where the search criteria matches in a file, not
+ just the most recent revision. It shows +/- to indicate whether the
+ change adds or removes your search text.
+
+
+Search tabs are named after the search string most recently used to
+start a search. The *New Search* toolbar button will obviously open a
+new search tab while the *Stop* button will terminate an ongoing search
+(the *Stop* button is only 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
+will bring up a context menu with these features:
+
+*display change*
+ open a changeset window with this changeset, to see the full context
+*annotate file*
+ open an annotation tab for this file at this revision
+*file history*
+ open a changelog window with this file's revision history
+
+Annotate Tabs
+-------------
+
+.. figure:: figures/annotate.png
+ :alt: Annotate tabs
+
+ Annotate tabs
+
+
+The revision graph has a simple context menu for opening the entire
+changeset in the changeset browser. Activating a row in the revision
+graph updates the file annotation to that revision.
+
+In the bottom pane is the actual annotation. Each line in the annotation
+is also a link to the changeset which provided that line. Activating a
+row will open that changeset in the changeset browser.
+
+The color scheme in the annotation pane is two tier. Authors are
+determined by hue, and age is determined by saturation. The older a
+change is, the lighter the color becomes.
+
+By right-clicking on the annotate pane's column headers (Line, Rev,
+Source) you can bring up a menu for showing two optional columns:
+*filename* and *user*.
+
+Configurables
+~~~~~~~~~~~~~
+
+The annotate tabs support the following configurations defined primarily
+for other tools:
+
+*Changelog->Author Coloring*
+ Give each author a separate color in the changelog graph
+*TortoiseHg->Tab width*
+ Number of spaces to expand tabs in diffs and annotate output
|
|
@@ -0,0 +1,65 @@ + ============================
+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
+other Tortoise client, such as TortoiseCVS and TortoiseSVN.
+
+Beginning from TortoiseHg version 0.5, the overlay icons are shared with
+TortoiseSVN (version 1.5.x or later) via the support of TortoiseOverlays
+(another project created by TortoiseSVN team).
+
+.. figure:: figures/overlayicons.png
+ :alt: Overlay icons
+
+ Overlay icons in Icons view (this image shows release 0.7 overlays)
+
+In release 0.8, we added an *Update Icons* context menu option which
+forces TortoiseHg to refresh the icons in the currently browsed
+repository or directory of repositories. The taskbar icon will turn
+green and the directory icons will turn into question marks while this
+refresh is in progress.
+
+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
+displaying/refreshing the windows explorer. In most cases, the delay is
+more prominent when the first time the repositories are viewed.
+Subsequently the caching of the file system usually helps to reduce the
+delay rather significantly.
+
+The delay may also be felt on repositories located on network drives or
+other slower media.
+
+In 0.8, the new C++ shell extension is an order of magnitude faster than
+the Python extension used in previous releases, but we still make the
+overlays configurable via the taskbar menu. Simply click on the
+Mercurial (droplet) icon in the system tray and select *Options*. In
+the options dialog you can disable overlays globally, or enable them for
+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
+context sensitive, which varies according to the folder being viewed.
+
+.. figure:: figures/contextmenu.png
+ :alt: Context menu
+
+ Context menu for a folder under Mercurial revision control (version 0.7)
+
+Currently TortoiseHg provides only the most regularly used Mercurial
+commands, hence the less frequently used, or newly add, Mercurial
+commands may still need be accessed on the CLI (command line interface)
+through the ``cmd.exe`` windows.
+
+In 0.8, the new C++ shell extension makes the context menu somewhat
+configurable via the taskbar menu. Simply click on the Mercurial
+(droplet) icon in the system tray and select *Options*. In the options
+dialog you can promote individual menu options to the top menu.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@@ -0,0 +1,31 @@ + .. TortoiseHG documentation master file, created by
+ sphinx-quickstart on Tue Jul 21 13:14:26 2009.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to TortoiseHG's documentation!
+======================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ common
+ explorer
+ commit
+ shelve
+ changelog
+ datamine
+ synchronize
+ serve
+ settings
+ recovery
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
|
|
@@ -0,0 +1,29 @@ + ===================
+TortoiseHg Recovery
+===================
+
+This page describes the 0.7 version of recovery, though very little was
+changed in 0.8
+
+.. figure:: figures/recover.png
+ :alt: Recovery dialog
+
+The buttons all equate to a single Mercurial command (save stop, obviously)
+
+*clean*
+ ``hg update --clean`` - performs a clean checkout of the existing
+ working directory parent revision. Undoes a partially completed
+ merge.
+
+*rollback*
+ ``hg rollback`` - undo operation for most recent repository
+ transaction. Can undo a commit or pull.
+
+*recover*
+ ``hg recover`` - recover from a badly aborted operation. Rarely
+ necessary, Mercurial will tell you if it needs to be performed.
+
+*verify*
+ ``hg verify`` - perform a consistency check of the contents of your
+ repository
+
|
|
@@ -0,0 +1,49 @@ + ================
+TortoiseHg Serve
+================
+
+The serve tool is a wrapper for Mercurial's built-in web server. Once
+launched, any computer can attach to the http port and browse your
+repository(ies) or perform clone, pull, or even push operations (if you
+configure your server to allow it).
+
+.. figure:: figures/serve.png
+ :alt: Web server dialog
+
+*Start*
+ start the web server
+
+*Stop*
+ stop the web server
+
+*Browse*
+ open your default browser at the built-in web server
+
+*Configure*
+ Configure repository web style, description, and access policies
+
+When the settings dialog is launched via the *Configure* button, it is
+run in the context of the current repository. Please visit the
+Mercurial wiki for detailed descriptions of what the various web
+configurations are for.
+
+If you wish to serve a many repositories with a single web server
+instance, you can create an ``hgwebdir.conf`` text file with the
+following contents: ::
+
+ [paths]
+ / = /path/to/repositories/*
+
+The first path '/' is where the repositories will appear in the context
+of the web server and the second path describes here the repositories
+can be found on your computer. Multiple entries are possible.
+
+To use this file you must launch the TortoiseHg serve dialog from the
+command line via: ``hgtk serve --webdir-conf=hgwebdir.conf``. In a
+future release of TortoiseHg, we hope to make this launchable from the
+shell context menu.
+
+Changes in 0.8
+--------------
+* Improved error handling
+* i18n fixes
|
|
@@ -0,0 +1,67 @@ + ===================
+TortoiseHg Settings
+===================
+
+This page describes the 0.7 version of settings
+
+The Settings dialog is used to configure both TortoiseHg and the
+underlying Mercurial DVCS. Since TortoiseHg uses Mercurial's underlying
+configuration system to store and retrieve its settings, these are
+essentially the same thing.
+
+Mercurial on Windows has a three-tier configuration system.
+
+1) A site-wide configuration file in ``C:\Program Files\TortoiseHg\Mercurial.ini`` This file is read first and thus has the lowest priority.
+2) A per-user configuration file in ``C:\Documents and Settings\username\Mercurial.ini`` This file is read second and thus can override settings in the site-wide configuration file.
+3) A per-repository configuration file in ``repo-root\.hg\hgrc`` This file is read last and can override site-wide and user global settings.
+
+The site-wide file can be overwritten on upgrades so it is recommended
+that you do not make changes to this file. Instead, you should make
+changes to your user ``Mercurial.ini`` and/or the repository hgrc file.
+The TortoiseHg Settings dialog enforces this suggestion by only
+operating in two modes:
+
+Global
+ edits your user ``Mercurial.ini`` file
+Repository
+ edits a repository ``.hg/hgrc`` file
+
+Most TortoiseHg users will want to store all configurables in their
+global user settings, and only use the repository hgrc to store paths
+(remote repository aliases) and web settings, though it is possible to
+override many configurables per-repository (a common example is to
+configure a different username for use in a repository). Also note that
+the user and repository configuration files may not exist until you run
+the Settings dialog for the first time.
+
+The Settings tool is a tabbed application.
+
+.. figure:: figures/settings.png
+ :alt: Settings dialog
+
+ Settings dialog
+
+Each tab corresponds roughly to a section of your ``Mercurial.ini``
+file, though there is a certain amount of overlap. Some sections were
+split across multiple tabs for clarity.
+
+Every tab except of the *Paths* tab has the same format, a list of
+configurable options with a drop-down combo box with possible values and
+a history of options you have used for that setting. The configurable
+name (label) has a tooltip which describes in more detail what you are
+configuring and its default value.
+
+The *Paths* tab is where you can store URLs (paths) to related
+repositories. It is rare to store paths in the site-wide or user
+configuration files, most of the time you will only store these in a
+repository configuration file. Mercurial has two special path names that
+can be used as default targets for some operations.
+
+default
+ the default URL to pull from, usually clone source
+default-push
+ the default push target when using the command line
+
+Please consult the Mercurial wiki for more detailed information about
+these configurables (except for the first three tabs: *TortoiseHg*,
+*Commit*, *Changelog*, which are specifically for TortoiseHg).
|
|
|
@@ -0,0 +1,120 @@ + ======================
+TortoiseHg Shelve Tool
+======================
+
+**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.**
+
+.. 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, the buttons perform the following tasks:
+
+*Refresh*
+ Reload the state of the working directory. It retains file check and
+ selection state across refresh, but not hunks.
+*Shelve*
+ Shelve selected diffs in checked files.
+*Unshelve*
+ Replace the shelved changes back into the working directory.
+*Revert*
+ Revert checked files to last revisioned state.
+*Add*
+ Add checked files that were in unknown *?* state.
+ These files will then be versioned as soon as they are committed.
+*Move*
+ Move checked files to specified target directory.
+ This move is done with Mercurial's full knowledge.
+*Remove*
+ Delete checked unversioned files and/or remove (mark as deleted) any
+ versioned files.
+*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.
+
+Below the file list are checkboxes that toggle the inclusion of the
+various classes of files {modified, added, removed, deleted, unknown,
+clean, ignored}.
+
+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
+changes are removed from the working directory and placed in a patch
+file. If the shelf already had changes in it, you will be asked whether
+to replace those changes or to merge these new changes into it. When
+the shelf has changes, the unshelve button will be active.
+
+When the unshelve button is pressed, the shelved changes are reapplied
+to the working directory.
+
+How is this different than 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
+on it while the shelved changes are gone. This is safer than selecting
+changes at build time since you can test whether the change being
+committed is valid.
+
+Shelving changes is also useful for removing partially completed work to
+make sure it doesn't interfere with the debugging of other changes you
+are making.
+
+Caveat: the shelved changes are stored in a patch that is based on the
+current working directory contents. There's no guarantee that the patch
+can be cleanly reapplied later if the shelved changes conflict with
+changes made to your code after the shelving.
+
+How is this different than 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).
+
+How is this different than 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.
+
+Keyboard navigation
+-------------------
+
+*CTRL-Q*
+ will close the top dialog window
+*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.
+
+Note that the code in the shelve tool that copies the hunks to the
+clipboard is smart 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.
+
+
+Configurables
+-------------
+
+* *TortoiseHg->Bottom Diffs*
+* *TortoiseHg->Tab Width*
|
|
|
@@ -0,0 +1,108 @@ + ======================
+TortoiseHg Synchronize
+======================
+
+This page describes the 0.7 version of synchronize
+
+The synchronize tool is used to transmit changesets between repositories
+and to email recipients.
+
+
+.. figure:: figures/synchronize.png
+ :alt: Synchronize dialog
+
+ Synchronize dialog
+
+*Incoming*
+ show changesets that would be pulled from target repository
+*Pull*
+ pull incoming changesets from target repository [1]
+*Outgoing*
+ show changesets that would be pushed to target repository
+*Push*
+ push outgoing changesets to target repository
+*Email*
+ send outgoing changesets (to target repository) as email
+*Stop*
+ stop current operation
+*Configure*
+ Configure repository paths (aliases)
+
+1) The *Pull* toolbutton has a drop-down menu with extra options that
+are only applicable to pull operations: *Update after Pull*, and *Use
+fetch*. See the fetch extension documentation for it's behavior.
+
+The *Repo:* button will open a directory finder to locate another
+repository on your local computer to synchronize with. Similarly, the
+*Bundle* button will open a file finder to locate a Mercurial bundle
+(``.hg``) file to pull changes from.
+
+The text entry/combo box is where you enter or select paths of target
+repositories. The synchronize tool will seed the drop-down list with
+path aliases configured for this repository, and with the most 10 recent
+paths used with any repository. There will be a dashed separator between
+the configured paths and the history.
+
+The *use proxy* button is a quick way to disable your proxy
+configuration for just a few operations. The button is only sensitive
+when you have an http proxy configured.
+
+All operations which require authentication will pop up dialog boxes to
+get the required information from the user. TortoiseHg uses the
+TortoisePlink tool (borrowed from the TortoiseSVN distribution) to
+handle *ssh:* connections and authentication. See the FAQ1_ for help if
+you have trouble connecting to ssh servers.
+
+.. _FAQ1: http://bitbucket.org/tortoisehg/stable/wiki/FAQ#tortoisehg-faq
+
+Under the *Advanced Options* fold-up panel are a number of configurables
+that are valid for most push/pull operations.
+
+*Specify target revision for transmission*
+ to avoid sending all revisions
+*Force pull or push*
+ override warnings about multiple heads or unrelated repositories
+*Show patches*
+ show diffs in incoming and outging changes
+*Show Newest First*
+ reverse order that changesets are listed
+*Show No Merges*
+ filter out merge changesets from output (does not affect push/pull)
+
+
+After Pull
+----------
+
+After changesets are pulled into your repository, two buttons may appear
+at the bottom of the dialog:
+
+*View pulled changesets*
+ Open the changelog viewer and inspect pulled changesets
+*Update to tip*
+ Update your working directory to the new tip
+
+Either button may be hidden if it is not applicable.
+
+Email
+-----
+
+The email dialog can be launched from two TortoiseHg tools.
+
+1) The changelog tool, in which case the user intends to email a single
+revision
+
+2) The synchronize tool, in which case the user intends to email all
+outgoing changes to the current target repository (it's good practice to
+check the outgoing changes before launching the email dialog).
+
+.. figure:: figures//email.png
+ :alt: Email dialog
+
+ Email dialog
+
+The *Send* button is obvious, and the *Configure* dialog predictably
+opens the TortoiseHg Settings dialog to the email tab where you can
+configure your SMTP settings and set default To: and From: addresses.
+
+Please consult the Mercurial documentation for the differences between
+plain patches, HG patches, Git patches, and bundles.
|
Loading...