From 3b256e30a953d70b7ae55709b15207725463e611 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 28 Oct 2016 11:04:05 -0700 Subject: [PATCH] Drop all hg-related questions from the FAQ. Questions already moved were left. Otherwise Git is covered well enough online that we should avoid duplicating documenting anything that isn't specific to our suggested workflow. --- committing.rst | 5 +- coredev.rst | 20 +-- faq.rst | 407 ++----------------------------------------------- 3 files changed, 23 insertions(+), 409 deletions(-) diff --git a/committing.rst b/committing.rst index e14c128273..8eb0b1629a 100644 --- a/committing.rst +++ b/committing.rst @@ -248,6 +248,9 @@ issue's page in the tracker, for each mentioned issue. If "closes" (or "closed", or "closing") is prepended, the issue is automatically closed as "fixed". +.. _issue tracker: https://bugs.python.org + + Working with Git_ ======================= @@ -280,7 +283,7 @@ If you use Git as a committer of patches (your own or others), you should set up some basic options. Here are the minimal options you need to activate: * Your *name* and *email*: these settings defines what will be used when you - :ref:`commit ` changes:: + commit changes:: git config --global user.name "Your Name" git config --global user.email email@example.org diff --git a/coredev.rst b/coredev.rst index 1458115ca0..2622e8b460 100644 --- a/coredev.rst +++ b/coredev.rst @@ -183,9 +183,9 @@ an existing one), you use the command:: ``PATH`` is optional: if it is omitted, all changes in your working copy will be committed to the local repository. When you commit, be sure that all -changes are desired by :ref:`reviewing them first `; -also, when making commits that you intend to push to public repositories, -you should **not** commit together unrelated changes. +changes are desired by reviewing them first; also, when making commits that you +intend to push to public repositories, you should **not** commit together +unrelated changes. To abort a commit that you are in the middle of, leave the message empty (i.e., close the text editor without adding any text for the @@ -289,17 +289,13 @@ committing*. 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. +First, this should not happen if you take the habit of reviewing changes before +committing them. In any case, run:: - hg backout + git revert This will modify your working copy so that all changes in ```` -(including added or deleted files) are undone. You then need to :ref:`commit -` these changes so that the backout gets permanently recorded. - -.. note:: - These instructions are for Mercurial 1.7 and higher. ``hg backout`` has - a slightly different behaviour in versions before 1.7. +(including added or deleted files) are undone. You then need to commit +these changes so that the backout gets permanently recorded. diff --git a/faq.rst b/faq.rst index 6f63cf94f4..518b4c6603 100644 --- a/faq.rst +++ b/faq.rst @@ -62,10 +62,12 @@ appear next to their name. Version Control =============== -For everyone ------------- - The following FAQs are intended for both core developers and contributors. +Please realize that Git is a heavily-documented tool, so using your favorite +search engine to find an answer to your question will more than likely work. + +Everyone +-------- Where can I learn about the version control system used, Git? ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' @@ -181,8 +183,8 @@ best to run a ``make distclean`` to ensure that all previously built files are removed. -I want to keep a separate working copy per development branch, is it possible? -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +I want to keep a separate working copy per development branch, is it's possible? +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' Create several clones of your local repository:: @@ -223,8 +225,9 @@ in the remote, use:: $ git log origin/master.. This is the list of changes that will be sent if you call -``git push``. It does **not** include any :ref:`uncommitted -changes ` in your working copy! +``git push``. It does **not** include any uncommitted +changes in your working copy (use ``git status`` to find out what is +not staged for committal)! Conversely, for the list of changes that are in the remote repository but not in the local, use:: @@ -275,395 +278,7 @@ replace ``-p1`` with ``-p0``. If the patch contains renames, deletions or copies, and you intend committing it after your review, you might prefer using:: - hg import --no-commit somework.patch - -If you want to work on the patch using mq_ (Mercurial Queues), type instead:: - - hg qimport somework.patch - -This will create a patch in your queue with a name that matches the filename. -You can use the ``-n`` argument to specify a different name. To have the -patch applied to the working copy, type:: - - hg qpush - -Finally, to delete the patch, first un-apply it if necessary using ``hg qpop``, -then do:: - - hg qdelete somework.patch - -.. _extended diff format: http://www.selenic.com/mercurial/hg.1.html#diffs -.. _mq: https://www.mercurial-scm.org/wiki/MqExtension - - -.. _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. -We suggest you try the mpatch_ utility, which can help resolve a number of -common causes of patch rejects. - -To make use of ``mpatch`` transparent, you can define a shell alias in one -of your startup files. For example, if you want it to open the ``kdiff3`` -merge program to fix failing patch hunks:: - - alias patch='mpatch --merge=kdiff3' - -or if you want it to automatically solve conflicts by using heuristics:: - - alias patch='mpatch --auto --no-merge' - -.. _mpatch: http://oss.oracle.com/~mason/mpatch/ - - -How do I add a file or directory to the repository? -''''''''''''''''''''''''''''''''''''''''''''''''''' - -Simply specify the path to the file or directory to add and run:: - - hg add PATH - -If ``PATH`` is a directory, Mercurial will recursively add any files in that -directory and its descendants. - -If you want Mercurial to figure out by itself which files should be added -and/or removed, just run:: - - hg addremove - -**Be careful** though, as it might add some files that are not desired in -the repository (such as build products, cache files, or other data). - -You will then need to run ``hg commit`` (as discussed below) to commit -the file(s) to your local repository. - - -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``:: - - hg copy module.rst module2.rst - -and then remove the parts that are not necessary from ``module.rst`` and -``module2.rst``. This allows Mercurial to know that the content of -``module2.rst`` used to be in ``module.rst``, and will make subsequent merges -easier. If necessary, you can also use ``hg copy`` several times. - -If you simply create ``module2.rst``, add it with ``hg add``, and copy part of -the content from ``module.rst``, Mercurial won't know that the two file are -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: https://www.mercurial-scm.org/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 ``update`` to a previous 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: https://www.mercurial-scm.org/wiki/ -.. _extensions: https://www.mercurial-scm.org/wiki/UsingExtensions -.. _tips and tricks: https://www.mercurial-scm.org/wiki/TipsAndTricks -.. _configuration options: http://www.selenic.com/mercurial/hgrc.5.html - - -.. _core-devs-faqs: - -For core developers -------------------- - -These FAQs are intended mainly for core developers. - - -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:: - - hg commit [PATH] - -``PATH`` is optional: if it is omitted, all changes in your working copy -will be committed to the local repository. When you commit, be sure that all -changes are desired by :ref:`reviewing them first `; -also, when making commits that you intend to push to public repositories, -you should **not** commit together unrelated changes. - -To abort a commit that you are in the middle of, leave the message -empty (i.e., close the text editor without adding any text for the -message). Mercurial will then abort the commit operation so that you can -try again later. - -Once a change is committed to your local repository, it is still only visible -by you. This means you are free to experiment with as many local commits -you feel like. - -.. note:: - If you do not like the default text editor Mercurial uses for - entering commit messages, you may specify a different editor, - either by changing the ``EDITOR`` environment variable or by setting - a Mercurial-specific editor in your global ``.hgrc`` with the ``editor`` - option in the ``[ui]`` section. - - -How do I solve merge conflicts? -''''''''''''''''''''''''''''''' - -The easiest way is to install KDiff3 --- Mercurial will open it automatically -in case of conflicts, and you can then use it to solve the conflicts and -save the resulting file(s). KDiff3 will also take care of marking the -conflicts as resolved. - -If you don't use a merge tool, you can use ``hg resolve --list`` to list the -conflicting files, resolve the conflicts manually, and the use -``hg resolve --mark `` to mark these conflicts as resolved. -You can also use ``hg resolve -am`` to mark all the conflicts as resolved. - -.. note:: - Mercurial will use KDiff3 automatically if it's installed and it can find - it --- you don't need to change any settings. KDiff3 is also already - included in the installer of TortoiseHg. For more information, see - https://www.mercurial-scm.org/wiki/KDiff3. - - -How do I make a null merge? -''''''''''''''''''''''''''' - -If you committed something (e.g. on 3.6) that shouldn't be ported on newer -branches (e.g. on default), you have to do a *null merge*:: - - cd 3.x - hg merge 3.6 - hg revert -ar default - hg resolve -am # needed only if the merge created conflicts - hg ci -m '#12345: null merge with 3.6.' - -Before committing, ``hg status`` should list all the merged files as ``M``, -but ``hg diff`` should produce no output. This will record the merge without -actually changing the content of the files. - - -I got "abort: push creates new remote heads!" while pushing, what do I do? -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -If you see this message while pushing, it means that you committed something -on a clone that was not up to date, thus creating a new head. -This usually happens for two reasons: - -1. You forgot to run ``hg pull`` and/or ``hg up`` before committing; -2. Someone else pushed on the main repo just before you, causing a push race; - -First of all you should pull the new changesets using ``hg pull``. Then you can -use ``hg heads`` to see which branches have multiple heads. - -If only one branch has multiple heads, you can do:: - - cd default - hg heads . - hg up csid-of-the-other-head - hg merge - hg ci -m 'Merge heads.' - -``hg heads .`` will show you the two heads of the current branch: the one you -pulled and the one you created with your commit (you can also specify a branch -with ``hg heads ``). While not strictly necessary, it is highly -recommended to switch to the other head before merging. This way you will be -merging only your changeset with the rest, and in case of conflicts it will be -a lot easier. - -If more than one branch has multiple heads, you have to repeat these steps for -each branch. Since this creates new changesets, you will also have to -:ref:`merge them between branches `. For example, if both ``3.6`` -and ``default`` have multiple heads, you should first merge heads in ``3.6``, -then merge heads in ``default``, and finally merge ``3.6`` with ``default`` -using ``hg merge 3.6`` as usual. - -In order to avoid this, you should *always remember to pull and update before -committing*. - - -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. - -In any case, run:: - - hg backout - -This will modify your working copy so that all changes in ```` -(including added or deleted files) are undone. You then need to :ref:`commit -` these changes so that the backout gets permanently recorded. - -.. note:: - These instructions are for Mercurial 1.7 and higher. ``hg backout`` has - a slightly different behaviour in versions before 1.7. + git apply somework.patch General