Update PEP 103 (#43)
* [PEP-103] Remove deprecated msysGit * [PEP-103] Fix URLs for sites that has been moved * [PEP-103] Link to the repository for git-cola * [PEP-103] Move around paragraphs about updating remote-tracking branches * [PEP-103] Two spaces before inline comments as per PEP-8 * [PEP-103] Explain problems with rebasing long-lived merged branches * [PEP-103] Add links to collections of useful assets GitAlias, GitIgnore and pre-commit hooks. * [PEP-103] git switches to the root dir before running any command * [PEP-103] Demote advanced topics to made them subtopics * [PEP-103] Fix a misspelling * [PEP-103] Config options don't need to be global
This commit is contained in:
Oleg Broytman
Berker Peksag
parent
d910fabad7
commit
72431922e7
133
pep-0103.txt
133
pep-0103.txt
|
|
@ -82,18 +82,18 @@ Unix users: `download and install using your package manager
|
|||
<https://git-scm.com/download/linux>`_.
|
||||
|
||||
Microsoft Windows: download `git-for-windows
|
||||
<https://github.com/git-for-windows/git/releases>`_ or `msysGit
|
||||
<https://github.com/msysgit/msysgit/releases>`_.
|
||||
<https://github.com/git-for-windows/git/releases>`_.
|
||||
|
||||
MacOS X: use git installed with `XCode
|
||||
<https://developer.apple.com/xcode/downloads/>`_ or download from
|
||||
`MacPorts <https://www.macports.org/ports.php?by=name&substr=git>`_ or
|
||||
<https://developer.apple.com/xcode/>`_ or download from `MacPorts
|
||||
<https://www.macports.org/ports.php?by=name&substr=git>`_ or
|
||||
`git-osx-installer
|
||||
<http://sourceforge.net/projects/git-osx-installer/files/>`_ or
|
||||
install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
|
||||
|
||||
`git-cola <https://git-cola.github.io/index.html>`_ is a Git GUI
|
||||
written in Python and GPL licensed. Linux, Windows, MacOS X.
|
||||
`git-cola <https://git-cola.github.io/index.html>`_ (`repository
|
||||
<https://github.com/git-cola/git-cola>`_) is a Git GUI written in
|
||||
Python and GPL licensed. Linux, Windows, MacOS X.
|
||||
|
||||
`TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
|
||||
to Git based on TortoiseSVN; open source.
|
||||
|
|
@ -193,18 +193,28 @@ remote-tracking branches, creates a local branch ``v1``, configure it
|
|||
to track upstream remotes/origin/v1 branch and checks out ``v1`` into
|
||||
the working directory.
|
||||
|
||||
Some commands, like ``git status``, report the difference between
|
||||
local and remote branches. Please remember they only do comparison
|
||||
with remote-tracking branches in your local repository, and the state
|
||||
of those remote-tracking branches can be outdated. To update
|
||||
remote-tracking branches you either fetch and merge (or rebase)
|
||||
commits from the remote repository or update remote-tracking branches
|
||||
without updating local branches.
|
||||
Some commands, like ``git status --branch`` and ``git branch --verbose``,
|
||||
report the difference between local and remote branches.
|
||||
Please remember they only do comparison with remote-tracking branches
|
||||
in your local repository, and the state of those remote-tracking
|
||||
branches can be outdated. To update remote-tracking branches you
|
||||
either fetch and merge (or rebase) commits from the remote repository
|
||||
or update remote-tracking branches without updating local branches.
|
||||
|
||||
|
||||
Updating local and remote-tracking branches
|
||||
-------------------------------------------
|
||||
|
||||
To update remote-tracking branches without updating local branches run
|
||||
``git remote update [$REMOTE...]``. For example::
|
||||
|
||||
$ git remote update
|
||||
$ git remote update origin
|
||||
|
||||
|
||||
Fetch and pull
|
||||
''''''''''''''
|
||||
|
||||
There is a major difference between
|
||||
|
||||
::
|
||||
|
|
@ -352,12 +362,6 @@ That changed in git 2.3, but see `the blog post
|
|||
for caveats; in 2.4 the push-to-deploy feature was `further improved
|
||||
<https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
|
||||
|
||||
To update remote-tracking branches without updating local branches run
|
||||
``git remote update [$REMOTE...]``. For example::
|
||||
|
||||
$ git remote update
|
||||
$ git remote update origin
|
||||
|
||||
|
||||
Tags
|
||||
''''
|
||||
|
|
@ -528,11 +532,11 @@ For example, if you want to reset the branch ``master`` back to the
|
|||
original commit but preserve two commits created in the current branch
|
||||
do something like::
|
||||
|
||||
$ git branch save-master # create a new branch saving master
|
||||
$ git reflog # find the original place of master
|
||||
$ git branch save-master # create a new branch saving master
|
||||
$ git reflog # find the original place of master
|
||||
$ git reset $COMMIT_ID
|
||||
$ git cherry-pick save-master~ save-master
|
||||
$ git branch -D save-master # remove temporary branch
|
||||
$ git branch -D save-master # remove temporary branch
|
||||
|
||||
|
||||
git revert: revert a commit
|
||||
|
|
@ -588,10 +592,10 @@ that it is very much recommended not to rebase published commits the
|
|||
question's diminished even further: "whether to use rebase on
|
||||
non-pushed commits?"
|
||||
|
||||
That small question is for the team to decide. The author of the PEP
|
||||
recommends to use rebase when pulling, i.e. always do ``git pull
|
||||
--rebase`` or even configure automatic setup of rebase for every new
|
||||
branch::
|
||||
That small question is for the team to decide. To preserve the beauty
|
||||
of linear history it's recommended to use rebase when pulling, i.e. do
|
||||
``git pull --rebase`` or even configure automatic setup of rebase for
|
||||
every new branch::
|
||||
|
||||
$ git config branch.autosetuprebase always
|
||||
|
||||
|
|
@ -634,6 +638,18 @@ The topic branch is deleted to avoid cluttering branch namespace with
|
|||
small topic branches. Information on what issue was fixed or what
|
||||
feature was implemented should be in the commit messages.
|
||||
|
||||
But even that small amount of rebasing could be too big in case of
|
||||
long-lived merged branches. Imagine you're doing work in both ``v1``
|
||||
and ``master`` branches, regularly merging ``v1`` into ``master``.
|
||||
After some time you will have a lot of merge and non-merge commits in
|
||||
``master``. Then you want to push your finished work to a shared
|
||||
repository and find someone has pushed a few commits to ``v1``. Now
|
||||
you have a choice of two equally bad alternatives: either you fetch
|
||||
and rebase ``v1`` and then have to recreate all you work in ``master``
|
||||
(reset ``master`` to the origin, merge ``v1`` and cherry-pick all
|
||||
non-merge commits from the old master); or merge the new ``v1`` and
|
||||
loose the beauty of linear history.
|
||||
|
||||
|
||||
Null-merges
|
||||
===========
|
||||
|
|
@ -698,6 +714,25 @@ command. For example::
|
|||
$ git check-attr -a -- \*.py
|
||||
|
||||
|
||||
Useful assets
|
||||
-------------
|
||||
|
||||
`GitAlias <http://gitalias.com/>`_ (`repository
|
||||
<https://github.com/GitAlias/gitalias>`_) is a big collection of
|
||||
aliases. A careful selection of aliases for frequently used commands
|
||||
could save you a lot of keystrokes!
|
||||
|
||||
`GitIgnore <https://www.gitignore.io/>`_ and
|
||||
https://github.com/github/gitignore are collections of ``.gitignore``
|
||||
files for all kinds of IDEs and programming languages. Python
|
||||
included!
|
||||
|
||||
`pre-commit <http://pre-commit.com/>`_ (`repositories
|
||||
<https://github.com/pre-commit>`_) is a framework for managing and
|
||||
maintaining multi-language pre-commit hooks. The framework is written
|
||||
in Python and has a lot of plugins for many programming languages.
|
||||
|
||||
|
||||
Advanced topics
|
||||
===============
|
||||
|
||||
|
|
@ -737,8 +772,36 @@ See `WhatIsTheIndex
|
|||
Wiki.
|
||||
|
||||
|
||||
Root
|
||||
----
|
||||
|
||||
Git switches to the root (top-level directory of the project where
|
||||
``.git`` subdirectory exists) before running any command. Git
|
||||
remembers though the directory that was current before the switch.
|
||||
Some programs take into account the current directory. E.g., ``git
|
||||
status`` shows file paths of changed and unknown files relative to the
|
||||
current directory; ``git grep`` searches below the current directory;
|
||||
``git apply`` applies only those hunks from the patch that touch files
|
||||
below the current directory.
|
||||
|
||||
But most commands run from the root and ignore the current directory.
|
||||
Imagine, for example, that you have two work trees, one for the branch
|
||||
``v1`` and the other for ``master``. If you want to merge ``v1`` from
|
||||
a subdirectory inside the second work tree you must write commands as
|
||||
if you're in the top-level dir. Let take two work trees,
|
||||
``project-v1`` and ``project``, for example::
|
||||
|
||||
$ cd project/subdirectory
|
||||
$ git fetch ../project-v1 v1:v1
|
||||
$ git merge v1
|
||||
|
||||
Please note the path in ``git fetch ../project-v1 v1:v1`` is
|
||||
``../project-v1`` and not ``../../project-v1`` despite the fact that
|
||||
we run the commands from a subdirectory, not from the root.
|
||||
|
||||
|
||||
ReReRe
|
||||
======
|
||||
------
|
||||
|
||||
Rerere is a mechanism that helps to resolve repeated merge conflicts.
|
||||
The most frequent source of recurring merge conflicts are topic
|
||||
|
|
@ -759,7 +822,7 @@ working tree::
|
|||
$ git config rerere.autoupdate true
|
||||
|
||||
You don't need to turn rerere on globally - you don't want rerere in
|
||||
bare repositories or single-branche repositories; you only need rerere
|
||||
bare repositories or single-branch repositories; you only need rerere
|
||||
in repos where you often perform merges and resolve merge conflicts.
|
||||
|
||||
See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
|
||||
|
|
@ -767,7 +830,7 @@ Book.
|
|||
|
||||
|
||||
Database maintenance
|
||||
====================
|
||||
--------------------
|
||||
|
||||
Git object database and other files/directories under ``.git`` require
|
||||
periodic maintenance and cleanup. For example, commit editing left
|
||||
|
|
@ -825,17 +888,17 @@ has an option ``-O`` that passes a list of names of the found files to
|
|||
a program; default program for ``-O`` is a pager (usually ``less``),
|
||||
but you can use your editor::
|
||||
|
||||
$ git grep -Ovim # but not -O vim
|
||||
$ git grep -Ovim # but not -O vim
|
||||
|
||||
BTW, if git is instructed to use ``less`` as the pager (i.e., if pager
|
||||
is not configured in git at all it uses ``less`` by default, or if it
|
||||
gets ``less`` from GIT_PAGER or PAGER environment variables, or if it
|
||||
was configured with ``git config --global core.pager less``, or
|
||||
was configured with ``git config [--global] core.pager less``, or
|
||||
``less`` is used in the command ``git grep -Oless``) ``git grep``
|
||||
passes ``+/$pattern`` option to ``less`` which is quite convenient.
|
||||
Unfortunately, ``git grep`` doesn't pass the pattern if the pager is
|
||||
not exactly ``less``, even if it's ``less`` with parameters (something
|
||||
like ``git config --global core.pager less -FRSXgimq``); fortunately,
|
||||
like ``git config [--global] core.pager less -FRSXgimq``); fortunately,
|
||||
``git grep -Oless`` always passes the pattern.
|
||||
|
||||
|
||||
|
|
@ -908,8 +971,8 @@ both are written in Python; pagure was written by Fedora developers
|
|||
and is being used to develop some Fedora projects. `GitPrep
|
||||
<http://gitprep.yukikimoto.com/>`_ is yet another Github clone,
|
||||
written in Perl. `Gogs <https://gogs.io/>`_ is written in Go.
|
||||
`GitBucket <https://takezoe.github.io/gitbucket/about/>`_ is written
|
||||
in Scala.
|
||||
`GitBucket <https://gitbucket.github.io/gitbucket-news/about/>`_ is
|
||||
written in Scala.
|
||||
|
||||
And last but not least, `Gitlab <https://about.gitlab.com/>`_. It's
|
||||
perhaps the most advanced web-based development environment for git.
|
||||
|
|
@ -945,7 +1008,7 @@ To work with the repository just use regular git commands including
|
|||
|
||||
To start converting your Mercurial habits to git see the page
|
||||
`Mercurial for Git users
|
||||
<https://mercurial.selenic.com/wiki/GitConcepts>`_ at Mercurial wiki.
|
||||
<https://www.mercurial-scm.org/wiki/GitConcepts>`_ at Mercurial wiki.
|
||||
At the second half of the page there is a table that lists
|
||||
corresponding Mercurial and git commands. Should work perfectly in
|
||||
both directions.
|
||||
|
|
|
|||
Loading…
Reference in New Issue