[Python-checkins] devguide: #14468: regroup the "Version control" FAQs in two sections: "for everyone" and
ezio.melotti
python-checkins at python.org
Tue Feb 26 03:33:36 CET 2013
http://hg.python.org/devguide/rev/3e213eaf85a6
changeset: 603:3e213eaf85a6
user: Ezio Melotti <ezio.melotti at gmail.com>
date: Tue Feb 26 04:32:10 2013 +0200
summary:
#14468: regroup the "Version control" FAQs in two sections: "for everyone" and "for committers".
files:
faq.rst | 437 ++++++++++++++++++++++---------------------
1 files changed, 224 insertions(+), 213 deletions(-)
diff --git a/faq.rst b/faq.rst
--- a/faq.rst
+++ b/faq.rst
@@ -132,8 +132,13 @@
Version Control
===============
+For everyone
+------------
+
+The following FAQs are intended for both core developers and contributors.
+
Where can I learn about the version control system used, Mercurial (hg)?
--------------------------------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Mercurial_'s (also known as ``hg``) official web site is at
http://mercurial.selenic.com/. A book on Mercurial published by
@@ -158,7 +163,7 @@
I already know how to use Git, can I use that instead?
-------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''
While the main workflow for core developers requires Mercurial, if
you just want to generate patches with ``git diff`` and post them to the
@@ -182,10 +187,10 @@
What do I need to use Mercurial?
--------------------------------------------------------------------------------
+''''''''''''''''''''''''''''''''
UNIX
-'''''''''''''''''''
+^^^^
First, you need to `download Mercurial`_. Most UNIX-based operating systems
have binary packages available. Most package management systems also
@@ -209,7 +214,7 @@
Windows
-'''''''''''''''''''
+^^^^^^^
The recommended option on Windows is to `download TortoiseHg`_ which
integrates with Windows Explorer and also bundles the command line client
@@ -236,7 +241,7 @@
What's a working copy? What's a repository?
--------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''
Mercurial is a "distributed" version control system. This means that each
participant, even casual contributors, download a complete copy (called a
@@ -259,7 +264,7 @@
Which branches are in my local repository?
-------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''
Typing ``hg branches`` displays the open branches in your local repository::
@@ -272,7 +277,7 @@
2.6 76213:f130ce67387d (inactive)
Why are some branches marked "inactive"?
-----------------------------------------
+''''''''''''''''''''''''''''''''''''''''
Assuming you get the following output::
@@ -287,7 +292,7 @@
.. _hg-current-branch:
Which branch is currently checked out in my working copy?
----------------------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Use::
@@ -307,7 +312,7 @@
.. _hg-switch-branches:
How do I switch between branches inside my working copy?
---------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Simply use ``hg update`` to checkout another branch in the current directory::
@@ -328,7 +333,7 @@
I want to keep a separate working copy per development branch, is it possible?
-------------------------------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Just clone your local repository and update each clone to a different branch::
@@ -343,21 +348,10 @@
changes, ``hg update`` will update to the head of the *current branch*.
-How do I avoid repeated pulls and pushes between my local repositories?
------------------------------------------------------------------------
-
-The "`share extension`_" allows you to share a single local repository
-between several working copies: each commit you make in a working copy will
-be immediately available in other working copies, even though they might
-be checked out on different branches.
-
-.. _share extension: http://mercurial.selenic.com/wiki/ShareExtension
-
-
.. _hg-paths:
How do I link my local repository to a particular remote repository?
--------------------------------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Your local repository is linked by default to the remote repository it
was *cloned* from. If you created it from scratch, however, it is not linked
@@ -375,7 +369,7 @@
How do I create a shorthand alias for a remote repository?
--------------------------------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
In your global ``.hgrc`` file add a section similar to the following::
@@ -392,7 +386,7 @@
How do I compare my local repository to a remote repository?
--------------------------------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
To display the list of changes that are in your local repository, but not
in the remote, use::
@@ -420,7 +414,7 @@
How do I update my local repository to be in sync with a remote repository?
--------------------------------------------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Run::
@@ -436,7 +430,7 @@
How do I update my working copy with the latest changes?
---------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Do::
@@ -455,7 +449,7 @@
.. _hg-local-workflow:
How do I apply a patch?
--------------------------------------------------------------------------------
+'''''''''''''''''''''''
If you want to try out or review a patch generated using Mercurial, do::
@@ -493,7 +487,7 @@
.. _merge-patch:
How do I solve conflicts when applying a patch fails?
------------------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''''''''''''
The standard ``patch`` command, as well as ``hg import``, will produce
unhelpful ``*.rej`` files when it fails applying parts of a patch.
@@ -514,7 +508,7 @@
How do I add a file or directory to the repository?
--------------------------------------------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''''''''''
Simply specify the path to the file or directory to add and run::
@@ -536,7 +530,7 @@
What's the best way to split a file into several files?
--------------------------------------------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
To split a file into several files (e.g. a module converted to a package or a
long doc file divided in two separate documents) use ``hg copy``::
@@ -553,10 +547,200 @@
related.
+How do I delete a file or directory in the repository?
+''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Specify the path to be removed with::
+
+ hg remove PATH
+
+This will remove the file or the directory from your working copy; you will
+have to :ref:`commit your changes <hg-commit>` for the removal to be recorded
+in your local repository.
+
+
+.. _hg-status:
+
+What files are modified in my working copy?
+'''''''''''''''''''''''''''''''''''''''''''
+
+Running::
+
+ hg status
+
+will list any pending changes in the working copy. These changes will get
+committed to the local repository if you issue an ``hg commit`` without
+specifying any path.
+
+Some
+key indicators that can appear in the first column of output are:
+
+ = ===========================
+ A Scheduled to be added
+ R Scheduled to be removed
+ M Modified locally
+ ? Not under version control
+ = ===========================
+
+If you want a line-by-line listing of the differences, use::
+
+ hg diff
+
+
+How do I revert a file I have modified back to the version in the repository?
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Running::
+
+ hg revert PATH
+
+will revert ``PATH`` to its version in the repository, throwing away any
+changes you made locally. If you run::
+
+ hg revert -a
+
+from the root of your working copy it will recursively restore everything
+to match up with the repository.
+
+
+How do I find out who edited or what revision changed a line last?
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+You want::
+
+ hg annotate PATH
+
+This will output to stdout every line of the file along with which revision
+last modified that line. When you have the revision number, it is then
+easy to :ref:`display it in detail <hg-log-rev>`.
+
+
+.. _hg-log:
+
+How can I see a list of log messages for a file or specific revision?
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+To see the history of changes for a specific file, run::
+
+ hg log -v [PATH]
+
+That will list all messages of revisions which modified the file specified
+in ``PATH``. If ``PATH`` is omitted, all revisions are listed.
+
+If you want to display line-by-line differences for each revision as well,
+add the ``-p`` option::
+
+ hg log -vp [PATH]
+
+.. _hg-log-rev:
+
+If you want to view the differences for a specific revision, run::
+
+ hg log -vp -r <revision number>
+
+
+How can I see the changeset graph in my repository?
+'''''''''''''''''''''''''''''''''''''''''''''''''''
+
+In Mercurial repositories, changesets don't form a simple list, but rather
+a graph: every changeset has one or two parents (it's called a merge changeset
+in the latter case), and can have any number of children.
+
+The graphlog_ extension is very useful for examining the structure of the
+changeset graph. It is bundled with Mercurial.
+
+Graphical tools, such as TortoiseHG, will display the changeset graph
+by default.
+
+.. _graphlog: http://mercurial.selenic.com/wiki/GraphlogExtension
+
+
+How do I update to a specific release tag?
+''''''''''''''''''''''''''''''''''''''''''
+
+Run::
+
+ hg tags
+
+to get a list of tags. To update your working copy to a specific tag, use::
+
+ hg update <tag>
+
+
+How do I find which changeset introduced a bug or regression?
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+``hg bisect``, as the name indicates, helps you do a bisection of a range of
+changesets.
+
+You need two changesets to start the search: one that is "good"
+(doesn't have the bug), and one that is "bad" (has the bug). Usually, you
+have just noticed the bug in your working copy, so you can start with::
+
+ hg bisect --bad
+
+Then you must find a changeset that doesn't have the bug. You can conveniently
+choose a faraway changeset (for example a former release), and check that it
+is indeed "good". Then type::
+
+ hg bisect --good
+
+Mercurial will automatically bisect so as to narrow the range of possible
+culprits, until a single changeset is isolated. Each time Mercurial presents
+you with a new changeset, re-compile Python and run the offending test, for
+example::
+
+ make -j2
+ ./python -m test -uall test_sometest
+
+Then, type either ``hg bisect --good`` or ``hg bisect --bad`` depending on
+whether the test succeeded or failed.
+
+
+How come feature XYZ isn't available in Mercurial?
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Mercurial comes with many bundled extensions which can be explicitly enabled.
+You can get a list of them by typing ``hg help extensions``. Some of these
+extensions, such as ``color``, can prettify output; others, such as ``fetch``
+or ``graphlog``, add new Mercurial commands.
+
+There are also many `configuration options`_ to tweak various aspects of the
+command line and other Mercurial behaviour; typing `man hgrc`_ displays
+their documentation inside your terminal.
+
+In the end, please refer to the Mercurial `wiki`_, especially the pages about
+`extensions`_ (including third-party ones) and the `tips and tricks`_.
+
+
+.. _man hgrc: http://www.selenic.com/mercurial/hgrc.5.html
+.. _wiki: http://mercurial.selenic.com/wiki/
+.. _extensions: http://mercurial.selenic.com/wiki/UsingExtensions
+.. _tips and tricks: http://mercurial.selenic.com/wiki/TipsAndTricks
+.. _configuration options: http://www.selenic.com/mercurial/hgrc.5.html
+
+
+For core developers
+-------------------
+
+These FAQs are intended mainly for core developers.
+
+
+How do I avoid repeated pulls and pushes between my local repositories?
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The "`share extension`_" allows you to share a single local repository
+between several working copies: each commit you make in a working copy will
+be immediately available in other working copies, even though they might
+be checked out on different branches.
+
+.. _share extension: http://mercurial.selenic.com/wiki/ShareExtension
+
+
.. _hg-commit:
How do I commit a change to a file?
--------------------------------------------------------------------------------
+'''''''''''''''''''''''''''''''''''
To commit any changes to a file (which includes adding a new file or deleting
an existing one), you use the command::
@@ -586,66 +770,10 @@
option in the ``[ui]`` section.
-How do I delete a file or directory in the repository?
--------------------------------------------------------------------------------
-
-Specify the path to be removed with::
-
- hg remove PATH
-
-This will remove the file or the directory from your working copy; you will
-have to :ref:`commit your changes <hg-commit>` for the removal to be recorded
-in your local repository.
-
-
-.. _hg-status:
-
-What files are modified in my working copy?
--------------------------------------------------------------------------------
-
-Running::
-
- hg status
-
-will list any pending changes in the working copy. These changes will get
-committed to the local repository if you issue an ``hg commit`` without
-specifying any path.
-
-Some
-key indicators that can appear in the first column of output are:
-
- = ===========================
- A Scheduled to be added
- R Scheduled to be removed
- M Modified locally
- ? Not under version control
- = ===========================
-
-If you want a line-by-line listing of the differences, use::
-
- hg diff
-
-
-How do I revert a file I have modified back to the version in the repository?
--------------------------------------------------------------------------------
-
-Running::
-
- hg revert PATH
-
-will revert ``PATH`` to its version in the repository, throwing away any
-changes you made locally. If you run::
-
- hg revert -a
-
-from the root of your working copy it will recursively restore everything
-to match up with the repository.
-
-
.. _hg-merge:
How do I find out which revisions need merging?
------------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''''''
In unambiguous cases, Mercurial will find out for you if you simply try::
@@ -664,7 +792,7 @@
How do I list the files in conflict after a merge?
---------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''
Use::
@@ -674,7 +802,7 @@
How I mark a file resolved after I have resolved merge conflicts?
------------------------------------------------------------------
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Type::
@@ -685,60 +813,8 @@
If you are sure you have resolved all conflicts, use ``hg resolve -am``.
-How do I find out who edited or what revision changed a line last?
--------------------------------------------------------------------------------
-
-You want::
-
- hg annotate PATH
-
-This will output to stdout every line of the file along with which revision
-last modified that line. When you have the revision number, it is then
-easy to :ref:`display it in detail <hg-log-rev>`.
-
-
-.. _hg-log:
-
-How can I see a list of log messages for a file or specific revision?
----------------------------------------------------------------------
-
-To see the history of changes for a specific file, run::
-
- hg log -v [PATH]
-
-That will list all messages of revisions which modified the file specified
-in ``PATH``. If ``PATH`` is omitted, all revisions are listed.
-
-If you want to display line-by-line differences for each revision as well,
-add the ``-p`` option::
-
- hg log -vp [PATH]
-
-.. _hg-log-rev:
-
-If you want to view the differences for a specific revision, run::
-
- hg log -vp -r <revision number>
-
-
-How can I see the changeset graph in my repository?
----------------------------------------------------
-
-In Mercurial repositories, changesets don't form a simple list, but rather
-a graph: every changeset has one or two parents (it's called a merge changeset
-in the latter case), and can have any number of children.
-
-The graphlog_ extension is very useful for examining the structure of the
-changeset graph. It is bundled with Mercurial.
-
-Graphical tools, such as TortoiseHG, will display the changeset graph
-by default.
-
-.. _graphlog: http://mercurial.selenic.com/wiki/GraphlogExtension
-
-
How do I undo the changes made in a recent commit?
--------------------------------------------------------------------------------
+''''''''''''''''''''''''''''''''''''''''''''''''''
First, this should not happen if you take the habit of :ref:`reviewing changes
<hg-status>` before committing them.
@@ -756,71 +832,6 @@
a slightly different behaviour in versions before 1.7.
-How do I update to a specific release tag?
--------------------------------------------------------------------------------
-
-Run::
-
- hg tags
-
-to get a list of tags. To update your working copy to a specific tag, use::
-
- hg update <tag>
-
-
-How do I find which changeset introduced a bug or regression?
--------------------------------------------------------------
-
-``hg bisect``, as the name indicates, helps you do a bisection of a range of
-changesets.
-
-You need two changesets to start the search: one that is "good"
-(doesn't have the bug), and one that is "bad" (has the bug). Usually, you
-have just noticed the bug in your working copy, so you can start with::
-
- hg bisect --bad
-
-Then you must find a changeset that doesn't have the bug. You can conveniently
-choose a faraway changeset (for example a former release), and check that it
-is indeed "good". Then type::
-
- hg bisect --good
-
-Mercurial will automatically bisect so as to narrow the range of possible
-culprits, until a single changeset is isolated. Each time Mercurial presents
-you with a new changeset, re-compile Python and run the offending test, for
-example::
-
- make -j2
- ./python -m test -uall test_sometest
-
-Then, type either ``hg bisect --good`` or ``hg bisect --bad`` depending on
-whether the test succeeded or failed.
-
-
-How come feature XYZ isn't available in Mercurial?
---------------------------------------------------
-
-Mercurial comes with many bundled extensions which can be explicitly enabled.
-You can get a list of them by typing ``hg help extensions``. Some of these
-extensions, such as ``color``, can prettify output; others, such as ``fetch``
-or ``graphlog``, add new Mercurial commands.
-
-There are also many `configuration options`_ to tweak various aspects of the
-command line and other Mercurial behaviour; typing `man hgrc`_ displays
-their documentation inside your terminal.
-
-In the end, please refer to the Mercurial `wiki`_, especially the pages about
-`extensions`_ (including third-party ones) and the `tips and tricks`_.
-
-
-.. _man hgrc: http://www.selenic.com/mercurial/hgrc.5.html
-.. _wiki: http://mercurial.selenic.com/wiki/
-.. _extensions: http://mercurial.selenic.com/wiki/UsingExtensions
-.. _tips and tricks: http://mercurial.selenic.com/wiki/TipsAndTricks
-.. _configuration options: http://www.selenic.com/mercurial/hgrc.5.html
-
-
SSH
=======
@@ -831,7 +842,7 @@
adding to the list of keys.
UNIX
-'''''''''''''''''''
+''''
Run::
@@ -841,7 +852,7 @@
public key is the file ending in ``.pub``.
Windows
-'''''''''''''''''''
+'''''''
Use PuTTYgen_ to generate your public key. Choose the "SSH2 DSA" radio button,
have it create an OpenSSH formatted key, choose a password, and save the private
@@ -855,7 +866,7 @@
---------------------------------------------------------------------------------------
UNIX
-'''''''''''''''''''
+''''
Use ``ssh-agent`` and ``ssh-add`` to register your private key with SSH for
your current session. The simplest solution, though, is to use KeyChain_,
@@ -868,7 +879,7 @@
.. _pageant:
Windows
-'''''''''''''''''''
+'''''''
The Pageant program is bundled with TortoiseHg. You can find it in its
installation directory (usually ``C:\Program Files (x86)\TortoiseHg\``);
--
Repository URL: http://hg.python.org/devguide
More information about the Python-checkins
mailing list