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