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 ` 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: + +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 + + +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 + + +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 ` 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: - -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 - - -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 ` 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 - - -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\``);