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,
92 `TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
93 to Git based on TortoiseSVN; open source.
98 This simple code is often appears in documentation, but it is
99 important so let repeat it here. Git stores author and committer
100 names/emails in every commit, so configure your real name and
103 $ git config --global user.name "User Name"
104 $ git config --global user.email user.name@example.org
110 Examples of git commands in this PEP use the following approach. It is
111 supposed that you, the user, works with a local repository named
112 ``python`` that has an upstream remote repo named ``origin``. Your
113 local repo has two branches ``v1`` and ``v2``. For most examples the
114 currently checked out branch is ``v2``. That is, it's assumed you have
115 done something like that::
117 $ git clone -b v2 http://git.python.org/python.git
119 $ git branch v1 origin/v1
121 The last command creates a new local branch v1 and sets
122 remotes/origin/v1 as its upstream remote branch.
124 The same result can achieved with commands::
126 $ git clone -b v1 http://git.python.org/python.git
128 $ git checkout --track origin/v2
130 The last command creates a new local branch v2, sets
131 remotes/origin/v2 as its upstream remote branch and checks it out into
132 the working directory.
135 Branches and branches
136 =====================
138 Git terminology can be a bit misleading. Take, for example, the term
139 "branch". In git it has two meanings. A branch is a directed line of
140 commits (possibly with merges). And a branch is a label or a pointer
141 assigned to a line of commits. It is important to differentiate when
142 you talk about commits and when about their labels. Lines of commits
143 are by itself unnamed and are usually only lengthening and merging.
144 Labels, on the other hand, can be created, moved, renamed and deleted
148 Remote repository and remote branches
149 =====================================
151 Another example of slightly misleading terminology. Remote
152 repositories are really remote, you access them via network (well, a
153 remote repository can be on your local disk, but it's still remote
154 because it's not the current repo).
156 Remote branches, on the other hand, are branches (pointers to commits)
157 in your local repository. They are there for you to remember what
158 branches and commits have been pulled from and pushed to what remote
159 repos (you can pull from and push to many remotes). Remote branches
160 live under ``remotes/REMOTE`` namespaces, e.g. ``remotes/origin/v2``.
162 To see the status of remote branches run::
166 To see local and remote branches (and tags) pointing to commits::
170 You never do your own development on remote branches. You create a
171 local branch that has a remote branch as upstream and do development
172 on that local branch. On push git updates remote branches, and on pull
173 git updates remote branches and fast-forwards, merges or rebases local
176 When you do an initial clone like this::
178 $ git clone -b v1 http://git.python.org/python.git
180 git clones remote repository ``http://git.python.org/python.git`` to
181 directory ``python``, creates remote branches, creates a local branch
182 ``v1``, configure it to track upstream remotes/origin/v1 branch and
183 checks out ``v1`` into the working directory.
185 Updating local and remote branches
186 ----------------------------------
188 There is a major difference between
192 $ git fetch REMOTE BRANCH
198 $ git fetch REMOTE BRANCH:BRANCH
200 The first command fetches commits from the named BRANCH in the REMOTE
201 repository that are not in your repository and leaves the id (the
202 hash) of the head commit in file .git/FETCH_HEAD. But it doesn't
203 update any branch (doesn't move any pointer).
205 The second command fetches commits from the named BRANCH in the REMOTE
206 repository that are not in your repository and updates both the local
207 branch BRANCH and its upstream remote branch. But it refuses to update
208 branches in case of non-fast-forward. And it refuses to update the
211 The first command is used internally by ``git pull``.
215 $ git pull REMOTE BRANCH
221 $ git fetch REMOTE BRANCH
222 $ git merge FETCH_HEAD # FETCH_HEAD is a literal here
224 Certainly, BRANCH in that case should be your current branch. If you
225 want to merge a different branch into your current branch first update
226 that non-current branch and then merge::
228 $ git fetch origin v1:v1 # Update v1
229 $ git pull --rebase origin v2 # Update the current branch v2 using
230 # rebase instead of merge
233 If you have not yet pushed commits on ``v1``, though, the scenario has
234 to become a bit more complex. Git refuses to update
235 non-fast-forwardable branch, and you don't want to do force-pull
236 because that would remove your non-pushed commits and you would need
237 to recover. So you want to rebase ``v1`` but you cannot rebase
238 non-current branch. Hence, checkout ``v1`` and rebase it before
242 $ git pull --rebase origin v1
244 $ git pull --rebase origin v2
247 It is possible to configure git to make it fetch/pull a few branches
248 or all branches at once, so you can simply run
263 Pushing is a bit simpler. There is only one command ``push``. When you
268 $ git push origin v1 v2
270 git guesses (knowing upstream remote branches) that you really want
274 $ git push origin v1:v1 v2:v2
276 Git pushes commits to the remote repo and updates remote branches. Git
277 refuses to push commits that aren't fast-forwardable. You can
278 force-push anyway, but please remember - you can force-push to your
279 own repositories but don't force-push to public or shared repos. If
280 you find git refuses to push commits that aren't fast-forwardable,
281 better fetch and merge commits from the remote repo (or rebase your
282 commits on top of the fetched commits), then push. Only force-push if
283 you know what you do and why you do it. See the section `Commit
284 editing and caveats`_ below.
286 It is possible to configure git to make it push a few branches or all
287 branches at once, so you can simply run
299 Git refuses to push a branch if it's the current branch in the remote
300 non-bare repository: git refuses to update remote working directory.
301 You really should push only to bare repositories. For non-bare
302 repositories git prefers pull-based workflow.
304 When you want to deploy code on a remote host and can only use push
305 (because your workstation is behind a firewall and you cannot pull
306 from it) you do that in two steps using two repositories: you push
307 from the workstation to a bare repo on the remote host, ssh to the
308 remote host and pull from the bare repo to a non-bare deployment repo.
313 Git automatically fetches tags that point to commits being fetched
314 during fetch/pull. To fetch all tags (and commits they point to) run
315 ``git fetch --tags origin``. To fetch some specific tags fetch them
318 $ git fetch origin tag TAG1 tag TAG2...
322 $ git fetch origin tag 1.4.2 tag 2.1.7
324 Git doesn't automatically pushes tags. That allows you to have private
325 tags (lightweight tags are also private for a repo, they cannot be
326 pushed). To push tags list them explicitly::
328 $ git push origin tag 1.4.2
329 $ git push origin v1 v2 tag 2.1.7
331 Don't move tags with ``git tag -f`` after they have been published.
334 Commit editing and caveats
335 ==========================
337 A warning not to edit published (pushed) commits also appears in
338 documentation but it's repeated here anyway as it's very important.
340 It is possible to recover from forced push but it's PITA for the
341 entire team. Please avoid it.
343 To see what commits have not been published yet compare the head of the
344 branch with its upstream remote branch::
346 $ git log origin/v2..
347 $ git log origin/v1..v1
349 For every branch that has an upstream remote branch git maintains an
350 alias @{upstream} (short version @{u}), so the commands above can be
356 To see the status of all branches::
360 To compare the status of local branches with a remote repo::
362 $ git remote show origin
364 Read `how to recover from upstream rebase
365 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
366 It is in ``git help rebase``.
368 On the other hand don't be too afraid about commit editing. You can
369 safely edit, remove, reorder, combine and split commits that hasn't
370 been pushed yet. You can even push commits to your own (backup) repo,
371 edit them later and force-push edited commits to replace what has
372 already been pushed. Not a problem until commits are in a public
373 or shared repository.
379 TODO: describe undo strategies: git reset, git revert, git checkout,
380 git reflog. "Commit early, commit often".
383 https://kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html
389 Internet is full of heated discussions on the topic: "merge or
390 rebase?" Most of them are meaningless. When a DVCS is being used in a
391 big team with a big and complex project with many branches there is
392 simply no way to avoid merges. So the question diminished to "whether
393 to use rebase, and if yes - when to use rebase?" Considering that it
394 is very much recommended not to rebase published commits the question
395 diminished even further: "whether to use rebase on non-pushed
398 That small question is for the team to decide. The author of the PEP
399 recommends to use rebase when pulling, i.e. always do ``git pull
400 --rebase`` or even configure automatic setup of rebase for every new
403 $ git config branch.autosetuprebase true
405 and configure rebase for existing branches::
407 $ git config branch.NAME.rebase true
409 After that ``git pull origin v2`` will be equivalent to ``git pull
410 --rebase origin v2``.
412 In case when merge is preferred it is recommended to create new
413 commits in a separate feature or topic branch while using rebase to
414 update the mainline branch. When the topic branch is ready merge it
415 into mainline. To avoid a tedious task of resolving conflicts you can
416 merge the topic branch to the mainline from time to time and switch
417 back to the topic branch to continue working on it. The entire
418 workflow would be something like::
420 $ git checkout -b issue-42 # create and switch to a new branch
421 ...edit/test/commit...
423 $ git pull --rebase origin v2 # update v2 from the upstream
425 $ git branch -d issue-42 # delete the topic branch
428 When the topic branch is deleted only the label is removed, commits
429 are stayed in the database, they are now merged into v2::
431 --o--o--o--o--o--o-M-<v2 - it is the mainline branch
433 --*--*--* - it is the topic branch, now unnamed
435 The topic branch is deleted to avoid cluttering branch namespace with
436 small topic branches. Information on what issue was fixed or what
437 feature was implemented should be in the commit messages.
443 Git has a builtin strategy for what Python core developers call
446 $ git merge -s ours v1 # null-merge v1 into v2
452 https://git-scm.com/book/en/Git-Tools-Rerere
461 Staging area aka index is a distinguishing feature of git. See
463 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
464 `IndexCommandQuickref
465 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
469 Advanced configuration
470 ======================
475 Git has builtin mechanisms to handle line endings.
477 TODO: describe crlf configuration and .gitattributes.
483 TODO: dangling objects, git gc, git repack.
489 TODO: sticky options; example: git grep -O.
491 TODO: bash/zsh completion, bash/zsh prompt.
497 TODO: anonymous access; git over ssh; gitolite; gitweb; cgit; gitlab.
500 From Mercurial to git
501 =====================
503 Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts
505 https://github.com/felipec/git-remote-hg
507 https://hg-git.github.io/
519 This document has been placed in the public domain.
526 indent-tabs-mode: nil
527 sentence-end-double-space: t
531 vim: set fenc=us-ascii tw=70 :