2 Title: Collecting information about git
5 Author: Oleg Broytman <phd@phdru.name>
8 Content-Type: text/x-rst
15 This Informational PEP collects information about git. There is, of
16 course, a lot of documentation for git, so the PEP concentrates on
17 more complex issues, scenarios and topics.
19 The plan is to extend the PEP in the future collecting information
20 about equivalence of Mercurial and git scenarios to help migrating
21 Python development from Mercurial to git.
23 The author of the PEP doesn't currently plan to write a Process PEP on
24 migration from Mercurial to git.
30 Git is accompanied with a lot of documentation, both online and
33 Documentation for starters
34 --------------------------
37 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>`_,
39 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial-2.html>`_.
42 <https://www.kernel.org/pub/software/scm/git/docs/user-manual.html>`_.
43 `Everyday GIT With 20 Commands Or So
44 <https://www.kernel.org/pub/software/scm/git/docs/everyday.html>`_.
46 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
49 <http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html>`_,
50 also with a number of translations.
52 Advanced documentation
53 ----------------------
55 `Pro Git <https://git-scm.com/book>`_. The Book about git. Buy it at
56 Amazon or download in PDF, mobi, or ePub form. Has translations to
57 many different languages. Download Russian translation from `GArik
58 <https://github.com/GArik/progit/wiki>`_.
60 `Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
65 Git has builtin help: run ``git help TOPIC``. For example, run
66 ``git help git`` or ``git help help``.
72 Download and installation
73 -------------------------
75 Unix users: download and install using your package manager.
77 Microsoft Windows: download `git-for-windows
78 <https://github.com/git-for-windows/git/releases>`_ or `msysGit
79 <https://github.com/msysgit/msysgit/releases>`_.
81 MacOS X: use git installed with `XCode
82 <https://developer.apple.com/xcode/downloads/>`_ or download from
83 `MacPorts <https://www.macports.org/ports.php?by=name&substr=git>`_ or
85 <http://sourceforge.net/projects/git-osx-installer/files/>`_ or
86 install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
88 `git-cola <https://git-cola.github.io/index.html>`_ is a sleek and
89 powerful Git GUI written in Python and GPL licensed. Linux, Windows,
95 This simple code is often appears in documentation, but it is
96 important so let repeat it here. Git stores author and committer
97 names/emails in every commit, so configure your real name and
100 $ git config --global user.name "User Name"
101 $ git config --global user.email user.name@example.org
107 Examples of git commands in this PEP use the following approach. It is
108 supposed that you, the user, works with a local repository named
109 ``python`` that has an upstream remote repo named ``origin``. Your
110 local repo has two branches ``v1`` and ``v2``. For most examples the
111 currently checked out branch is ``v2``. That is, it's assumed you have
112 done something like that::
114 $ git clone -b v2 http://git.python.org/python.git
116 $ git branch v1 origin/v1
118 The last command creates a new local branch v1 and sets
119 remotes/origin/v1 as its upstream remote branch.
121 The same result can achieved with commands::
123 $ git clone -b v1 http://git.python.org/python.git
125 $ git checkout --track origin/v2
127 The last command creates a new local branch v2, sets
128 remotes/origin/v2 as its upstream remote branch and checks it out into
129 the working directory.
132 Branches and branches
133 =====================
135 Git terminology can be a bit misleading. Take, for example, the term
136 "branch". In git it has two meanings. A branch is a directed line of
137 commits (possibly with merges). And a branch is a label or a pointer
138 assigned to a line of commits. It is important to differentiate when
139 you talk about commits and when about their labels. Lines of commits
140 are by itself unnamed and are usually only lengthening and merging.
141 Labels, on the other hand, can be created, moved, renamed and deleted
145 Remote repository and remote branches
146 =====================================
148 Another example of slightly misleading terminology. Remote
149 repositories are really remote, you access them via network (well, a
150 remote repository can be on your local disk, but it's still remote
151 because it's not the current repo).
153 Remote branches, on the other hand, are branches (pointers to commits)
154 in your local repository. They are there for you to remember what
155 branches and commits have been pulled from and pushed to what remote
156 repos (you can pull from and push to many remotes). Remote branches
157 live under ``remotes/REMOTE`` namespaces, e.g. ``remotes/origin/v2``.
159 To see the status of remote branches run::
163 To see local and remote branches (and tags) pointing to commits::
167 You never do your own development on remote branches. You create a
168 local branch that has a remote branch as upstream and do development
169 on that local branch. On push git updates remote branches, and on pull
170 git updates remote branches and fast-forwards, merges or rebases local
173 When you do an initial clone like this::
175 $ git clone -b v1 http://git.python.org/python.git
177 git clones remote repository ``http://git.python.org/python.git`` to
178 directory ``python``, creates remote branches, creates a local branch
179 ``v1``, configure it to track upstream remotes/origin/v1 branch and
180 checks out ``v1`` into the working directory.
182 Updating local and remote branches
183 ----------------------------------
185 There is a major difference between
189 $ git fetch REMOTE BRANCH
195 $ git fetch REMOTE BRANCH:BRANCH
197 The first command fetches commits from the named BRANCH in the REMOTE
198 repository that are not in your repository and leaves the id (the
199 hash) of the head commit in file .git/FETCH_HEAD. But it doesn't
200 update any branch (doesn't move any pointer).
202 The second command fetches commits from the named BRANCH in the REMOTE
203 repository that are not in your repository and updates both the local
204 branch BRANCH and its upstream remote branch. But it refuses to update
205 branches in case of non-fast-forward. And it refuses to update the
208 The first command is used internally by ``git pull``.
212 $ git pull REMOTE BRANCH
218 $ git fetch REMOTE BRANCH
219 $ git merge FETCH_HEAD # FETCH_HEAD is a literal here
221 Certainly, BRANCH in that case should be your current branch. If you
222 want to merge a different branch into your current branch first update
223 that non-current branch and then merge::
225 $ git fetch origin v1:v1 # Update v1
226 $ git pull --rebase origin v2 # Update the current branch v2 using
227 # rebase instead of merge
230 If you have not yet pushed commits on ``v1``, though, the scenario has
231 to become a bit more complex. Git refuses to update
232 non-fast-forwardable branch, and you don't want to do force-pull
233 because that would remove your non-pushed commits and you would need
234 to recover. So you want to rebase ``v1`` but you cannot rebase
235 non-current branch. Hence, checkout ``v1`` and rebase it before
239 $ git pull --rebase origin v1
241 $ git pull --rebase origin v2
244 It is possible to configure git to make it fetch/pull a few branches
245 or all branches at once, so you can simply run
260 Pushing is a bit simpler. There is only one command ``push``. When you
265 $ git push origin v1 v2
267 git guesses (knowing upstream remote branches) that you really want
271 $ git push origin v1:v1 v2:v2
273 Git pushes commits to the remote repo and updates remote branches. Git
274 refuses to push commits that aren't fast-forwardable. You can
275 force-push anyway, but please remember - you can force-push to your
276 own repositories but don't force-push to public or shared repos. If
277 you find git refuses to push commits that aren't fast-forwardable,
278 better fetch and merge commits from the remote repo (or rebase your
279 commits on top of the fetched commits), then push. Only force-push if
280 you know what you do and why you do it. See the section `Commit
281 editing and caveats`_ below.
283 It is possible to configure git to make it push a few branches or all
284 branches at once, so you can simply run
296 Git refuses to push a branch if it's the current branch in the remote
297 non-bare repository: git refuses to update remote working directory.
298 You really should push only to bare repositories. For non-bare
299 repositories git prefers pull-based workflow.
301 When you want to deploy code on a remote host and can only use push
302 (because your workstation is behind a firewall and you cannot pull
303 from it) you do that in two steps using two repositories: you push
304 from the workstation to a bare repo on the remote host, ssh to the
305 remote host and pull from the bare repo to a non-bare deployment repo.
310 Git automatically fetches tags that point to commits being fetched
311 during fetch/pull. To fetch all tags (and commits they point to) run
312 ``git fetch --tags origin``. To fetch some specific tags fetch them
315 $ git fetch origin tag TAG1 tag TAG2...
319 $ git fetch origin tag 1.4.2 tag 2.1.7
321 Git doesn't automatically pushes tags. That allows you to have private
322 tags (lightweight tags are also private for a repo, they cannot be
323 pushed). To push tags list them explicitly::
325 $ git push origin tag 1.4.2
326 $ git push origin v1 v2 tag 2.1.7
328 Don't move tags with ``git tag -f`` after they have been published.
331 Commit editing and caveats
332 ==========================
334 A warning not to edit published (pushed) commits also appears in
335 documentation but it's repeated here anyway as it's very important.
337 It is possible to recover from forced push but it's PITA for the
338 entire team. Please avoid it.
340 To see what commits have not been published yet compare the head of the
341 branch with its upstream remote branch::
343 $ git log origin/v2..
344 $ git log origin/v1..v1
346 For every branch that has an upstream remote branch git maintains an
347 alias @{upstream} (short version @{u}), so the commands above can be
353 To see the status of all branches::
357 To compare the status of local branches with a remote repo::
359 $ git remote show origin
361 Read `how to recover from upstream rebase
362 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
363 It is in ``git help rebase``.
365 On the other hand don't be too afraid about commit editing. You can
366 safely edit, remove, reorder, combine and split commits that hasn't
367 been pushed yet. You can even push commits to your own (backup) repo,
368 edit them later and force-push edited commits to replace what has
369 already been pushed. Not a problem until commits are in a public
370 or shared repository.
376 TODO: describe undo strategies: git reset, git revert, git checkout,
377 git reflog. "Commit early, commit often".
380 https://kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html
386 Internet is full of heated discussions on the topic: "merge or
387 rebase?" Most of them are meaningless. When a DVCS is being used in a
388 big team with a big and complex project with many branches there is
389 simply no way to avoid merges. So the question diminished to "whether
390 to use rebase, and if yes - when to use rebase?" Considering that it
391 is very much recommended not to rebase published commits the question
392 diminished even further: "whether to use rebase on non-pushed
395 That small question is for the team to decide. The author of the PEP
396 recommends to use rebase when pulling, i.e. always do ``git pull
397 --rebase`` or even configure automatic setup of rebase for every new
400 $ git config branch.autosetuprebase true
402 and configure rebase for existing branches::
404 $ git config branch.NAME.rebase true
406 After that ``git pull origin v2`` will be equivalent to ``git pull
407 --rebase origin v2``.
409 In case when merge is preferred it is recommended to create new
410 commits in a separate feature or topic branch while using rebase to
411 update the mainline branch. When the topic branch is ready merge it
412 into mainline. To avoid a tedious task of resolving conflicts you can
413 merge the topic branch to the mainline from time to time and switch
414 back to the topic branch to continue working on it. The entire
415 workflow would be something like::
417 $ git checkout -b issue-42 # create and switch to a new branch
418 ...edit/test/commit...
420 $ git pull --rebase origin v2 # update v2 from the upstream
422 $ git branch -d issue-42 # delete the topic branch
425 When the topic branch is deleted only the label is removed, commits
426 are stayed in the database, they are now merged into v2::
428 --o--o--o--o--o--o-M-<v2 - it is the mainline branch
430 --*--*--* - it is the topic branch, now unnamed
432 The topic branch is deleted to avoid cluttering branch namespace with
433 small topic branches. Information on what issue was fixed or what
434 feature was implemented should be in the commit messages.
440 Git has a builtin strategy for what Python core developers call
443 $ git merge -s ours v1 # null-merge v1 into v2
449 https://git-scm.com/book/en/Git-Tools-Rerere
458 Staging area aka index is a distinguishing feature of git. See
460 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
461 `IndexCommandQuickref
462 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
466 Advanced configuration
467 ======================
472 Git has builtin mechanisms to handle line endings.
474 TODO: describe crlf configuration and .gitattributes.
480 TODO: dangling objects, git gc, git repack.
486 TODO: sticky options; example: git grep -O.
488 TODO: bash/zsh completion, bash/zsh prompt.
494 TODO: anonymous access; git over ssh; gitolite; gitweb; cgit; gitlab.
497 From Mercurial to git
498 =====================
500 Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts
502 https://github.com/felipec/git-remote-hg
504 https://hg-git.github.io/
516 This document has been placed in the public domain.
523 indent-tabs-mode: nil
524 sentence-end-double-space: t
528 vim: set fenc=us-ascii tw=70 :