Version: $Revision$
Last-Modified: $Date$
Author: Oleg Broytman <phd@phdru.name>
-Status: Active
+Status: Draft
Type: Informational
Content-Type: text/x-rst
Created: 01-Jun-2015
This Informational PEP collects information about git. There is, of
course, a lot of documentation for git, so the PEP concentrates on
-more complex issues, topics and scenarios.
+more complex issues, scenarios and topics.
The plan is to extend the PEP in the future collecting information
about equivalence of Mercurial and git scenarios to help migrating
`Git workflows
<https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
+Advanced documentation
+----------------------
+
`Git Magic
<http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html>`_,
also with a number of translations.
-Advanced documentation
-----------------------
-
`Pro Git <https://git-scm.com/book>`_. The Book about git. Buy it at
Amazon or download in PDF, mobi, or ePub form. Has translations to
many different languages. Download Russian translation from `GArik
Offline documentation
---------------------
-Git has builtin help: run ``git help TOPIC``. For example, run
+Git has builtin help: run ``git help $TOPIC``. For example, run
``git help git`` or ``git help help``.
Download and installation
-------------------------
-Unix users: download and install using your package manager.
+Unix users: `download and install using your package manager
+<https://git-scm.com/download/linux>`_.
Microsoft Windows: download `git-for-windows
-<https://git-for-windows.github.io/>`_.
+<https://github.com/git-for-windows/git/releases>`_ or `msysGit
+<https://github.com/msysgit/msysgit/releases>`_.
MacOS X: use git installed with `XCode
-<https://developer.apple.com/xcode/downloads/>`_ or download
+<https://developer.apple.com/xcode/downloads/>`_ 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/>`_.
+<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.
+
+`TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
+to Git based on TortoiseSVN; open source.
Initial configuration
---------------------
This simple code is often appears in documentation, but it is
-important so let repeat it here::
+important so let repeat it here. Git stores author and committer
+names/emails in every commit, so configure your real name and
+preferred email::
$ git config --global user.name "User Name"
$ git config --global user.email user.name@example.org
Examples of git commands in this PEP use the following approach. It is
supposed that you, the user, works with a local repository named
``python`` that has an upstream remote repo named ``origin``. Your
-local repo has two branches ``v1`` and ``v2``. Usually the currently
-checked out branch is ``v2``.
+local repo has two branches ``v1`` and ``master``. For most examples
+the currently checked out branch is ``master``. That is, it's assumed
+you have done something like that::
+
+ $ git clone http://git.python.org/python.git
+ $ cd python
+ $ git branch v1 origin/v1
+
+The first command clones remote repository into local directory
+`python``, creates a new local branch master, sets
+remotes/origin/master as its upstream remote-tracking branch and
+checks it out into the working directory.
+
+The last command creates a new local branch v1 and sets
+remotes/origin/v1 as its upstream remote-tracking branch.
+
+The same result can be achieved with commands::
+
+ $ git clone -b v1 http://git.python.org/python.git
+ $ cd python
+ $ git checkout --track origin/master
+
+The last command creates a new local branch master, sets
+remotes/origin/master as its upstream remote-tracking branch and
+checks it out into the working directory.
+
+
+Branches and branches
+=====================
+
+Git terminology can be a bit misleading. Take, for example, the term
+"branch". In git it has two meanings. A branch is a directed line of
+commits (possibly with merges). And a branch is a label or a pointer
+assigned to a line of commits. It is important to distinguish when you
+talk about commits and when about their labels. Lines of commits are
+by itself unnamed and are usually only lengthening and merging.
+Labels, on the other hand, can be created, moved, renamed and deleted
+freely.
+
+
+Remote repositories and remote branches
+=======================================
+
+Remote-tracking branches are branches (pointers to commits) in your
+local repository. They are there for you to remember what branches and
+commits have been pulled from and pushed to what remote repos (you can
+pull from and push to many remotes). Remote-tracking branches live
+under ``remotes/$REMOTE`` namespaces, e.g. ``remotes/origin/master``.
+
+To see the status of remote-tracking branches run::
+
+ $ git branch -rv
+
+To see local and remote-tracking branches (and tags) pointing to
+commits::
+
+ $ git log --decorate
+
+You never do your own development on remote-tracking branches. You
+create a local branch that has a remote branch as upstream and do
+development on that local branch. On push git pushes commits to the
+remote repo and updates remote-tracking branches, on pull git fetches
+commits from the remote repo, updates remote-tracking branches and
+fast-forwards, merges or rebases local branches.
+
+When you do an initial clone like this::
+
+ $ git clone -b v1 http://git.python.org/python.git
+
+git clones remote repository ``http://git.python.org/python.git`` to
+directory ``python``, creates 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.
+
+Updating local and remote-tracking branches
+-------------------------------------------
+
+There is a major difference between
+
+::
+
+ $ git fetch $REMOTE $BRANCH
+
+and
+
+::
+
+ $ git fetch $REMOTE $BRANCH:$BRANCH
+
+The first command fetches commits from the named $BRANCH in the
+$REMOTE repository that are not in your repository, updates
+remote-tracking branch and leaves the id (the hash) of the head commit
+in file .git/FETCH_HEAD.
+
+The second command fetches commits from the named $BRANCH in the
+$REMOTE repository that are not in your repository and updates both
+the local branch $BRANCH and its upstream remote-tracking branch. But
+it refuses to update branches in case of non-fast-forward. And it
+refuses to update the current branch.
+
+The first command is used internally by ``git pull``.
+
+::
+
+ $ git pull $REMOTE $BRANCH
+
+is equivalent to
+
+::
+
+ $ git fetch $REMOTE $BRANCH
+ $ git merge FETCH_HEAD
+
+Certainly, $BRANCH in that case should be your current branch. If you
+want to merge a different branch into your current branch first update
+that non-current branch and then merge::
+
+ $ git fetch origin v1:v1 # Update v1
+ $ git pull --rebase origin master # Update the current branch master
+ # using rebase instead of merge
+ $ git merge v1
+
+If you have not yet pushed commits on ``v1``, though, the scenario has
+to become a bit more complex. Git refuses to update
+non-fast-forwardable branch, and you don't want to do force-pull
+because that would remove your non-pushed commits and you would need
+to recover. So you want to rebase ``v1`` but you cannot rebase
+non-current branch. Hence, checkout ``v1`` and rebase it before
+merging::
+
+ $ git checkout v1
+ $ git pull --rebase origin v1
+ $ git checkout master
+ $ git pull --rebase origin master
+ $ git merge v1
+
+It is possible to configure git to make it fetch/pull a few branches
+or all branches at once, so you can simply run
+
+::
+
+ $ git pull origin
+
+or even
+
+::
+
+ $ git pull
+
+Default remote repository for fetching/pulling is origin. Default set
+of references to fetch is calculated using matching algorithm: git
+fetches all branches having the same name on both ends.
+
+Push
+''''
+
+Pushing is a bit simpler. There is only one command ``push``. When you
+run
+
+::
+
+ $ git push origin v1 master
+
+git pushes local v1 to remote v1 and local master to remote master.
+The same as::
+
+ $ git push origin v1:v1 master:master
+
+Git pushes commits to the remote repo and updates remote-tracking
+branches. Git refuses to push commits that aren't fast-forwardable.
+You can force-push anyway, but please remember - you can force-push to
+your own repositories but don't force-push to public or shared repos.
+If you find git refuses to push commits that aren't fast-forwardable,
+better fetch and merge commits from the remote repo (or rebase your
+commits on top of the fetched commits), then push. Only force-push if
+you know what you do and why you do it. See the section `Commit
+editing and caveats`_ below.
+
+It is possible to configure git to make it push a few branches or all
+branches at once, so you can simply run
+
+::
+
+ $ git push origin
+
+or even
+
+::
+
+ $ git push
+
+Default remote repository for pushing is origin. Default set
+of references to push in git before 2.0 is calculated using matching
+algorithm: git pushes all branches having the same name on both ends.
+Default set of references to push in git 2.0+ is calculated using
+simple algorithm: git pushes the current branch back to its
+@{upstream}.
+
+To configure git before 2.0 to the new behaviour run::
+
+$ git config push.default simple
+
+To configure git 2.0+ to the old behaviour run::
+
+$ git config push.default matching
+
+Git refuses to push a branch if it's the current branch in the remote
+non-bare repository: git refuses to update remote working directory.
+You really should push only to bare repositories. For non-bare
+repositories git prefers pull-based workflow.
+
+When you want to deploy code on a remote host and can only use push
+(because your workstation is behind a firewall and you cannot pull
+from it) you do that in two steps using two repositories: you push
+from the workstation to a bare repo on the remote host, ssh to the
+remote host and pull from the bare repo to a non-bare deployment repo.
+
+That changed in git 2.3, but see `the blog post
+<https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
+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>`_.
+
+Tags
+''''
+
+Git automatically fetches tags that point to commits being fetched
+during fetch/pull. To fetch all tags (and commits they point to) run
+``git fetch --tags origin``. To fetch some specific tags fetch them
+explicitly::
+
+ $ git fetch origin tag $TAG1 tag $TAG2...
+
+For example::
+
+ $ git fetch origin tag 1.4.2
+ $ git fetch origin v1:v1 tag 2.1.7
+
+Git doesn't automatically pushes tags. That allows you to have private
+tags. To push tags list them explicitly::
+
+ $ git push origin tag 1.4.2
+ $ git push origin v1 master tag 2.1.7
+
+Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
+after they have been published.
+
+Private information
+'''''''''''''''''''
+
+When cloning/fetching/pulling/pushing git copies only database objects
+(commits, trees, files and tags) and symbolic references (branches and
+lightweight tags). Everything else is private to the repository and
+never cloned, updated or pushed. It's your config, your hooks, your
+private exclude file.
+
+If you want to distribute hooks, copy them to the working tree, add,
+commit, push and instruct the team to update ind install the hook
+manually.
Commit editing and caveats
==========================
A warning not to edit published (pushed) commits also appears in
-documentation but it's also repeated here as it's very important.
+documentation but it's repeated here anyway as it's very important.
It is possible to recover from forced push but it's PITA for the
entire team. Please avoid it.
-To see what commits have not been published yet see the head of the
-remote branch::
+To see what commits have not been published yet compare the head of the
+branch with its upstream remote-tracking branch::
- $ git log origin/v2..
+ $ git log origin/master..
+ $ git log origin/v1..v1
-For every branch that has an upstream remote branch git maintains an
-alias @{upstream} (short version @{u})::
+For every branch that has an upstream remote-tracking branch git
+maintains an alias @{upstream} (short version @{u}), so the commands
+above can be given as::
$ git log @{u}..
$ git log v1@{u}..v1
$ git branch -avv
+To compare the status of local branches with a remote repo::
+
+ $ git remote show origin
+
Read `how to recover from upstream rebase
<https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
It is in ``git help rebase``.
On the other hand don't be too afraid about commit editing. You can
-safely edit commits that hasn't been pushed yet. You can even push
-commits to your own (backup) repo, edit them later and force-push
-edited commits to replace what has already been pushed.
+safely edit, remove, reorder, combine and split commits that haven't
+been pushed yet. You can even push commits to your own (backup) repo,
+edit them later and force-push edited commits to replace what have
+already been pushed. Not a problem until commits are in a public
+or shared repository.
+
+
+Undo
+====
+
+Whatever you do, don't panic. Almost anything in git can be undone.
+
+git checkout: restore file's content
+------------------------------------
+
+``git checkout``, for example, can be used to restore the content of
+file(s) to that one of a commit. Like this::
+
+ git checkout HEAD~ README
+
+The commands restores the contents of README file to the last but one
+commit in the current branch. By default the commit ID is simply HEAD;
+i.e. ``git checkout README`` restores README to the latest commit.
+
+(Do not use ``git checkout`` to view a content of a file in a commit,
+use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
+
+git reset: remove (non-pushed) commits
+--------------------------------------
+
+``git reset`` moves the head of the current branch. The head can be
+moved to point to any commit but it's often used to remove a commit or
+a few (preferably, non-pushed ones) from the top of the branch - that
+is, to move the branch backward in order to undo a few (non-pushed)
+commits.
+
+``git reset`` has three modes of operation - soft, hard and mixed.
+Default is mixed. ProGit `explains
+<https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
+difference very clearly. Bare repositories don't have indices or
+working trees so in a bare repo only soft reset is possible.
+
+Unstaging
+'''''''''
+
+Mixed mode reset with a path or paths can be used to unstage changes -
+that is, to remove from index changes added with ``git add`` for
+committing. See `The Book
+<https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
+about unstaging and other undo tricks.
+
+git reflog: reference log
+-------------------------
+
+Removing commits with ``git reset`` or moving the head of a branch
+sounds dangerous and it is. But there is a way to undo: another
+reset back to the original commit. Git doesn't remove commits
+immediately; unreferenced commits (in git terminology they are called
+"dangling commits") stay in the database for some time (default is two
+weeks) so you can reset back to it or create a new branch pointing to
+the original commit.
+
+For every move of a branch's head - with ``git commit``, ``git
+checkout``, ``git fetch``, ``git pull``, ``git rebase``, ``git reset``
+and so on - git stores a reference log (reflog for short). For every
+move git stores where the head was. Command ``git reflog`` can be used
+to view (and manipulate) the log.
+
+In addition to the moves of the head of every branch git stores the
+moves of the HEAD - a symbolic reference that (usually) names the
+current branch. HEAD is changed with ``git checkout $BRANCH``.
+
+By default ``git reflog`` shows the moves of the HEAD, i.e. the
+command is equivalent to ``git reflog HEAD``. To show the moves of the
+head of a branch use the command ``git reflog $BRANCH``.
+
+So to undo a ``git reset`` lookup the original commit in ``git
+reflog``, verify it with ``git show`` or ``git log`` and run ``git
+reset $COMMIT_ID``. Git stores the move of the branch's head in
+reflog, so you can undo that undo later again.
+
+In a more complex situation you'd want to move some commits along with
+resetting the head of the branch. Cherry-pick them to the new branch.
+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 reset $COMMIT_ID
+ $ git cherry-pick save-master~ save-master
+ $ git branch -D save-master # remove temporary branch
+
+git revert: revert a commit
+---------------------------
+
+``git revert`` reverts a commit or commits, that is, it creates a new
+commit or commits that revert(s) the effects of the given commits.
+It's the only way to undo published commits (``git commit --amend``,
+``git rebase`` and ``git reset`` change the branch in
+non-fast-forwardable ways so they should only be used for non-pushed
+commits.)
+
+There is a problem with reverting a merge commit. ``git revert`` can
+undo the code created by the merge commit but it cannot undo the fact
+of merge. See the discussion `How to revert a faulty merge
+<https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
+
+One thing that cannot be undone
+-------------------------------
+
+Whatever you undo, there is one thing that cannot be undone -
+overwritten uncommitted changes. Uncommitted changes don't belong to
+git so git cannot help preserving them.
+
+Most of the time git warns you when you're going to execute a command
+that overwrites uncommitted changes. Git warns you when you try to
+switch branches with ``git checkout``. It warns you when you're going
+to rebase with non-clean working tree. It refuses to pull new commits
+over non-committed files.
+
+But there are commands that do exactly that - overwrite files in the
+working tree. Commands like ``git checkout $PATHs`` or ``git reset
+--hard`` silently overwrite files including your uncommitted changes.
+
+With that in mind you can understand the stance "commit early, commit
+often". Commit as often as possible. Commit on every save in your
+editor or IDE. You can edit your commits before pushing - change,
+reorder, combine, remove. But save your changes in git database,
+either commit changes or at least stash them with ``git stash``.
+
+
+Merge or rebase?
+================
+
+Internet is full of heated discussions on the topic: "merge or
+rebase?" Most of them are meaningless. When a DVCS is being used in a
+big team with a big and complex project with many branches there is
+simply no way to avoid merges. So the question's diminished to
+"whether to use rebase, and if yes - when to use rebase?" Considering
+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::
+
+ $ git config branch.autosetuprebase always
+
+and configure rebase for existing branches::
+
+ $ git config branch.$NAME.rebase true
+
+For example::
+
+ $ git config branch.v1.rebase true
+ $ git config branch.master.rebase true
+
+After that ``git pull origin master`` becomes equivalent to ``git pull
+--rebase origin master``.
+
+In case when merge is preferred it is recommended to create new
+commits in a separate feature or topic branch while using rebase to
+update the mainline branch. When the topic branch is ready merge it
+into mainline. To avoid a tedious task of resolving large number of
+conflicts at once you can merge the topic branch to the mainline from
+time to time and switch back to the topic branch to continue working
+on it. The entire workflow would be something like::
+
+ $ git checkout -b issue-42 # create a new issue branch and switch to it
+ ...edit/test/commit...
+ $ git checkout master
+ $ git pull --rebase origin master # update master from the upstream
+ $ git merge issue-42
+ $ git branch -d issue-42 # delete the topic branch
+ $ git push origin master
+
+When the topic branch is deleted only the label is removed, commits
+are stayed in the database, they are now merged into master::
+
+ o--o--o--o--o--M--< master - the mainline branch
+ \ /
+ --*--*--* - the topic branch, now unnamed
+
+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.
+
+
+Null-merges
+===========
+
+Git has a builtin merge strategy for what Python core developers call
+"null-merge"::
+
+ $ git merge -s ours v1 # null-merge v1 into master
+
+
+Advanced configuration
+======================
+
+Line endings
+------------
+
+Git has builtin mechanisms to handle line endings between platforms
+with different EOL styles. To allow git to do CRLF conversion assign
+``text`` attribute to files using `.gitattributes
+<https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
+For files that have to have specific line ending assign ``eol``
+attribute. For binary files the attribute is, naturally, ``binary``.
+
+For example::
+
+ $ cat .gitattributes
+ *.py text
+ *.txt text
+ *.png binary
+ /readme.txt eol=CRLF
+
+To check what attributes git uses for files use ``git check-attr``
+command. For example::
+
+$ git check-attr -a -- \*.py
+
+
+Advanced topics
+===============
+
+Staging area
+------------
+
+Staging area aka index aka cache is a distinguishing feature of git.
+Staging area is where git collects patches before committing them.
+Separation between collecting patches and commit phases provides a
+very useful feature of git: one can review collected patches before
+commit and even edit them - remove some hunks, add new hunks and
+review again.
+
+To add files to the index use ``git add``. Collecting patches before
+committing means you need to do that for every change, not only to add
+new (untracked) files. To simplify committing in case you just want to
+commit everything without reviewing run ``git commit --all`` (or just
+``-a``) - the command adds every changed tracked file to the index and
+then commit.
+
+To add hunks of patches to the index use ``git add --patch`` (or just
+``-p``). To remove collected files from the index use ``git reset HEAD
+-- $FILE...`` To add/inspect/remove collected hunks use ``git add
+--interactive`` (``-i``).
+
+To see the diff between the index and the last commit (i.e., collected
+patches) use ``git diff --cached``. To see the diff between the
+working tree and the index (i.e., uncollected patches) use just ``git
+diff``. To see the diff between the working tree and the last commit
+(i.e., both collected and uncollected patches) use ``git diff HEAD``.
+
+See `WhatIsTheIndex
+<https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
+`IndexCommandQuickref
+<https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
+Wiki.
+
+
+ReReRe
+======
+
+https://git-scm.com/book/en/Git-Tools-Rerere
+
+
+Database maintenance
+====================
+
+TODO: dangling objects, git gc, git repack.
+
+https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html
+
+http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html
+
+
+Tips and tricks
+===============
+
+TODO: sticky options; example: git grep -O.
+
+TODO: tricky options; example: git log -p3.
+
+TODO: bash/zsh completion, bash/zsh prompt.
+https://git.kernel.org/cgit/git/git.git/tree/contrib/completion
+
+
+git on server
+=============
+
+TODO: anonymous access; git over ssh; gitolite; gitweb; cgit; gitlab.
+
+http://gitolite.com/gitolite/index.html
+
+https://git.kernel.org/cgit/git/git.git/tree/gitweb
+
+http://git.zx2c4.com/cgit/
+
+From Mercurial to git
+=====================
+
+Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts
+
+https://github.com/felipec/git-remote-hg
+
+https://hg-git.github.io/
References
projects / git-wiki.git / blobdiff