2 Title: Collecting information about git
5 Author: Oleg Broytman <phd@phdru.name>
8 Content-Type: text/x-rst
10 Post-History: 12-Sep-2015
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 (and more related to Python development) issues,
18 scenarios and examples.
20 The plan is to extend the PEP in the future collecting information
21 about equivalence of Mercurial and git scenarios to help migrating
22 Python development from Mercurial to git.
24 The author of the PEP doesn't currently plan to write a Process PEP on
25 migration Python development from Mercurial to git.
31 Git is accompanied with a lot of documentation, both online and
35 Documentation for starters
36 --------------------------
39 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>`_,
41 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial-2.html>`_.
44 <https://www.kernel.org/pub/software/scm/git/docs/user-manual.html>`_.
45 `Everyday GIT With 20 Commands Or So
46 <https://www.kernel.org/pub/software/scm/git/docs/giteveryday.html>`_.
48 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
51 Advanced documentation
52 ----------------------
55 <http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html>`_,
56 with a number of translations.
58 `Pro Git <https://git-scm.com/book>`_. The Book about git. Buy it at
59 Amazon or download in PDF, mobi, or ePub form. It has translations to
60 many different languages. Download Russian translation from `GArik
61 <https://github.com/GArik/progit/wiki>`_.
63 `Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
65 `Git Buch <http://gitbu.ch/index.html>`_ (German).
71 Git has builtin help: run ``git help $TOPIC``. For example, run
72 ``git help git`` or ``git help help``.
78 Download and installation
79 -------------------------
81 Unix users: `download and install using your package manager
82 <https://git-scm.com/download/linux>`_.
84 Microsoft Windows: download `git-for-windows
85 <https://github.com/git-for-windows/git/releases>`_ or `msysGit
86 <https://github.com/msysgit/msysgit/releases>`_.
88 MacOS X: use git installed with `XCode
89 <https://developer.apple.com/xcode/downloads/>`_ or download from
90 `MacPorts <https://www.macports.org/ports.php?by=name&substr=git>`_ or
92 <http://sourceforge.net/projects/git-osx-installer/files/>`_ or
93 install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
95 `git-cola <https://git-cola.github.io/index.html>`_ is a Git GUI
96 written in Python and GPL licensed. Linux, Windows, MacOS X.
98 `TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
99 to Git based on TortoiseSVN; open source.
102 Initial configuration
103 ---------------------
105 This simple code is often appears in documentation, but it is
106 important so let repeat it here. Git stores author and committer
107 names/emails in every commit, so configure your real name and
110 $ git config --global user.name "User Name"
111 $ git config --global user.email user.name@example.org
117 Examples of git commands in this PEP use the following approach. It is
118 supposed that you, the user, works with a local repository named
119 ``python`` that has an upstream remote repo named ``origin``. Your
120 local repo has two branches ``v1`` and ``master``. For most examples
121 the currently checked out branch is ``master``. That is, it's assumed
122 you have done something like that::
124 $ git clone https://git.python.org/python.git
126 $ git branch v1 origin/v1
128 The first command clones remote repository into local directory
129 `python``, creates a new local branch master, sets
130 remotes/origin/master as its upstream remote-tracking branch and
131 checks it out into the working directory.
133 The last command creates a new local branch v1 and sets
134 remotes/origin/v1 as its upstream remote-tracking branch.
136 The same result can be achieved with commands::
138 $ git clone -b v1 https://git.python.org/python.git
140 $ git checkout --track origin/master
142 The last command creates a new local branch master, sets
143 remotes/origin/master as its upstream remote-tracking branch and
144 checks it out into the working directory.
147 Branches and branches
148 =====================
150 Git terminology can be a bit misleading. Take, for example, the term
151 "branch". In git it has two meanings. A branch is a directed line of
152 commits (possibly with merges). And a branch is a label or a pointer
153 assigned to a line of commits. It is important to distinguish when you
154 talk about commits and when about their labels. Lines of commits are
155 by itself unnamed and are usually only lengthening and merging.
156 Labels, on the other hand, can be created, moved, renamed and deleted
160 Remote repositories and remote branches
161 =======================================
163 Remote-tracking branches are branches (pointers to commits) in your
164 local repository. They are there for git (and for you) to remember
165 what branches and commits have been pulled from and pushed to what
166 remote repos (you can pull from and push to many remotes).
167 Remote-tracking branches live under ``remotes/$REMOTE`` namespaces,
168 e.g. ``remotes/origin/master``.
170 To see the status of remote-tracking branches run::
174 To see local and remote-tracking branches (and tags) pointing to
179 You never do your own development on remote-tracking branches. You
180 create a local branch that has a remote branch as upstream and do
181 development on that local branch. On push git pushes commits to the
182 remote repo and updates remote-tracking branches, on pull git fetches
183 commits from the remote repo, updates remote-tracking branches and
184 fast-forwards, merges or rebases local branches.
186 When you do an initial clone like this::
188 $ git clone -b v1 https://git.python.org/python.git
190 git clones remote repository ``https://git.python.org/python.git`` to
191 directory ``python``, creates a remote named ``origin``, creates
192 remote-tracking branches, creates a local branch ``v1``, configure it
193 to track upstream remotes/origin/v1 branch and checks out ``v1`` into
194 the working directory.
196 Some commands, like ``git status --branch`` and ``git branch --verbose``,
197 report the difference between local and remote branches.
198 Please remember they only do comparison with remote-tracking branches
199 in your local repository, and the state of those remote-tracking
200 branches can be outdated. To update remote-tracking branches you
201 either fetch and merge (or rebase) commits from the remote repository
202 or update remote-tracking branches without updating local branches.
205 Updating local and remote-tracking branches
206 -------------------------------------------
208 To update remote-tracking branches without updating local branches run
209 ``git remote update [$REMOTE...]``. For example::
212 $ git remote update origin
218 There is a major difference between
222 $ git fetch $REMOTE $BRANCH
228 $ git fetch $REMOTE $BRANCH:$BRANCH
230 The first command fetches commits from the named $BRANCH in the
231 $REMOTE repository that are not in your repository, updates
232 remote-tracking branch and leaves the id (the hash) of the head commit
233 in file .git/FETCH_HEAD.
235 The second command fetches commits from the named $BRANCH in the
236 $REMOTE repository that are not in your repository and updates both
237 the local branch $BRANCH and its upstream remote-tracking branch. But
238 it refuses to update branches in case of non-fast-forward. And it
239 refuses to update the current branch (currently checked out branch,
240 where HEAD is pointing to).
242 The first command is used internally by ``git pull``.
246 $ git pull $REMOTE $BRANCH
252 $ git fetch $REMOTE $BRANCH
253 $ git merge FETCH_HEAD
255 Certainly, $BRANCH in that case should be your current branch. If you
256 want to merge a different branch into your current branch first update
257 that non-current branch and then merge::
259 $ git fetch origin v1:v1 # Update v1
260 $ git pull --rebase origin master # Update the current branch master
261 # using rebase instead of merge
264 If you have not yet pushed commits on ``v1``, though, the scenario has
265 to become a bit more complex. Git refuses to update
266 non-fast-forwardable branch, and you don't want to do force-pull
267 because that would remove your non-pushed commits and you would need
268 to recover. So you want to rebase ``v1`` but you cannot rebase
269 non-current branch. Hence, checkout ``v1`` and rebase it before
273 $ git pull --rebase origin v1
274 $ git checkout master
275 $ git pull --rebase origin master
278 It is possible to configure git to make it fetch/pull a few branches
279 or all branches at once, so you can simply run
291 Default remote repository for fetching/pulling is ``origin``. Default
292 set of references to fetch is calculated using matching algorithm: git
293 fetches all branches having the same name on both ends.
299 Pushing is a bit simpler. There is only one command ``push``. When you
304 $ git push origin v1 master
306 git pushes local v1 to remote v1 and local master to remote master.
309 $ git push origin v1:v1 master:master
311 Git pushes commits to the remote repo and updates remote-tracking
312 branches. Git refuses to push commits that aren't fast-forwardable.
313 You can force-push anyway, but please remember - you can force-push to
314 your own repositories but don't force-push to public or shared repos.
315 If you find git refuses to push commits that aren't fast-forwardable,
316 better fetch and merge commits from the remote repo (or rebase your
317 commits on top of the fetched commits), then push. Only force-push if
318 you know what you do and why you do it. See the section `Commit
319 editing and caveats`_ below.
321 It is possible to configure git to make it push a few branches or all
322 branches at once, so you can simply run
334 Default remote repository for pushing is ``origin``. Default set of
335 references to push in git before 2.0 is calculated using matching
336 algorithm: git pushes all branches having the same name on both ends.
337 Default set of references to push in git 2.0+ is calculated using
338 simple algorithm: git pushes the current branch back to its
341 To configure git before 2.0 to the new behaviour run::
343 $ git config push.default simple
345 To configure git 2.0+ to the old behaviour run::
347 $ git config push.default matching
349 Git doesn't allow to push a branch if it's the current branch in the
350 remote non-bare repository: git refuses to update remote working
351 directory. You really should push only to bare repositories. For
352 non-bare repositories git prefers pull-based workflow.
354 When you want to deploy code on a remote host and can only use push
355 (because your workstation is behind a firewall and you cannot pull
356 from it) you do that in two steps using two repositories: you push
357 from the workstation to a bare repo on the remote host, ssh to the
358 remote host and pull from the bare repo to a non-bare deployment repo.
360 That changed in git 2.3, but see `the blog post
361 <https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
362 for caveats; in 2.4 the push-to-deploy feature was `further improved
363 <https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
369 Git automatically fetches tags that point to commits being fetched
370 during fetch/pull. To fetch all tags (and commits they point to) run
371 ``git fetch --tags origin``. To fetch some specific tags fetch them
374 $ git fetch origin tag $TAG1 tag $TAG2...
378 $ git fetch origin tag 1.4.2
379 $ git fetch origin v1:v1 tag 2.1.7
381 Git doesn't automatically pushes tags. That allows you to have private
382 tags. To push tags list them explicitly::
384 $ git push origin tag 1.4.2
385 $ git push origin v1 master tag 2.1.7
387 Or push all tags at once::
389 $ git push --tags origin
391 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
392 after they have been published.
398 When cloning/fetching/pulling/pushing git copies only database objects
399 (commits, trees, files and tags) and symbolic references (branches and
400 lightweight tags). Everything else is private to the repository and
401 never cloned, updated or pushed. It's your config, your hooks, your
402 private exclude file.
404 If you want to distribute hooks, copy them to the working tree, add,
405 commit, push and instruct the team to update and install the hooks
409 Commit editing and caveats
410 ==========================
412 A warning not to edit published (pushed) commits also appears in
413 documentation but it's repeated here anyway as it's very important.
415 It is possible to recover from a forced push but it's PITA for the
416 entire team. Please avoid it.
418 To see what commits have not been published yet compare the head of the
419 branch with its upstream remote-tracking branch::
421 $ git log origin/master.. # from origin/master to HEAD (of master)
422 $ git log origin/v1..v1 # from origin/v1 to the head of v1
424 For every branch that has an upstream remote-tracking branch git
425 maintains an alias @{upstream} (short version @{u}), so the commands
426 above can be given as::
431 To see the status of all branches::
435 To compare the status of local branches with a remote repo::
437 $ git remote show origin
439 Read `how to recover from upstream rebase
440 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
441 It is in ``git help rebase``.
443 On the other hand don't be too afraid about commit editing. You can
444 safely edit, reorder, remove, combine and split commits that haven't
445 been pushed yet. You can even push commits to your own (backup) repo,
446 edit them later and force-push edited commits to replace what have
447 already been pushed. Not a problem until commits are in a public
448 or shared repository.
454 Whatever you do, don't panic. Almost anything in git can be undone.
457 git checkout: restore file's content
458 ------------------------------------
460 ``git checkout``, for example, can be used to restore the content of
461 file(s) to that one of a commit. Like this::
463 git checkout HEAD~ README
465 The commands restores the contents of README file to the last but one
466 commit in the current branch. By default the commit ID is simply HEAD;
467 i.e. ``git checkout README`` restores README to the latest commit.
469 (Do not use ``git checkout`` to view a content of a file in a commit,
470 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
473 git reset: remove (non-pushed) commits
474 --------------------------------------
476 ``git reset`` moves the head of the current branch. The head can be
477 moved to point to any commit but it's often used to remove a commit or
478 a few (preferably, non-pushed ones) from the top of the branch - that
479 is, to move the branch backward in order to undo a few (non-pushed)
482 ``git reset`` has three modes of operation - soft, hard and mixed.
483 Default is mixed. ProGit `explains
484 <https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
485 difference very clearly. Bare repositories don't have indices or
486 working trees so in a bare repo only soft reset is possible.
492 Mixed mode reset with a path or paths can be used to unstage changes -
493 that is, to remove from index changes added with ``git add`` for
494 committing. See `The Book
495 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
496 about unstaging and other undo tricks.
499 git reflog: reference log
500 -------------------------
502 Removing commits with ``git reset`` or moving the head of a branch
503 sounds dangerous and it is. But there is a way to undo: another
504 reset back to the original commit. Git doesn't remove commits
505 immediately; unreferenced commits (in git terminology they are called
506 "dangling commits") stay in the database for some time (default is two
507 weeks) so you can reset back to it or create a new branch pointing to
510 For every move of a branch's head - with ``git commit``, ``git
511 checkout``, ``git fetch``, ``git pull``, ``git rebase``, ``git reset``
512 and so on - git stores a reference log (reflog for short). For every
513 move git stores where the head was. Command ``git reflog`` can be used
514 to view (and manipulate) the log.
516 In addition to the moves of the head of every branch git stores the
517 moves of the HEAD - a symbolic reference that (usually) names the
518 current branch. HEAD is changed with ``git checkout $BRANCH``.
520 By default ``git reflog`` shows the moves of the HEAD, i.e. the
521 command is equivalent to ``git reflog HEAD``. To show the moves of the
522 head of a branch use the command ``git reflog $BRANCH``.
524 So to undo a ``git reset`` lookup the original commit in ``git
525 reflog``, verify it with ``git show`` or ``git log`` and run ``git
526 reset $COMMIT_ID``. Git stores the move of the branch's head in
527 reflog, so you can undo that undo later again.
529 In a more complex situation you'd want to move some commits along with
530 resetting the head of the branch. Cherry-pick them to the new branch.
531 For example, if you want to reset the branch ``master`` back to the
532 original commit but preserve two commits created in the current branch
535 $ git branch save-master # create a new branch saving master
536 $ git reflog # find the original place of master
537 $ git reset $COMMIT_ID
538 $ git cherry-pick save-master~ save-master
539 $ git branch -D save-master # remove temporary branch
542 git revert: revert a commit
543 ---------------------------
545 ``git revert`` reverts a commit or commits, that is, it creates a new
546 commit or commits that revert(s) the effects of the given commits.
547 It's the only way to undo published commits (``git commit --amend``,
548 ``git rebase`` and ``git reset`` change the branch in
549 non-fast-forwardable ways so they should only be used for non-pushed
552 There is a problem with reverting a merge commit. ``git revert`` can
553 undo the code created by the merge commit but it cannot undo the fact
554 of merge. See the discussion `How to revert a faulty merge
555 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
558 One thing that cannot be undone
559 -------------------------------
561 Whatever you undo, there is one thing that cannot be undone -
562 overwritten uncommitted changes. Uncommitted changes don't belong to
563 git so git cannot help preserving them.
565 Most of the time git warns you when you're going to execute a command
566 that overwrites uncommitted changes. Git doesn't allow you to switch
567 branches with ``git checkout``. It stops you when you're going to
568 rebase with non-clean working tree. It refuses to pull new commits
569 over non-committed files.
571 But there are commands that do exactly that - overwrite files in the
572 working tree. Commands like ``git checkout $PATHs`` or ``git reset
573 --hard`` silently overwrite files including your uncommitted changes.
575 With that in mind you can understand the stance "commit early, commit
576 often". Commit as often as possible. Commit on every save in your
577 editor or IDE. You can edit your commits before pushing - edit commit
578 messages, change commits, reorder, combine, split, remove. But save
579 your changes in git database, either commit changes or at least stash
580 them with ``git stash``.
586 Internet is full of heated discussions on the topic: "merge or
587 rebase?" Most of them are meaningless. When a DVCS is being used in a
588 big team with a big and complex project with many branches there is
589 simply no way to avoid merges. So the question's diminished to
590 "whether to use rebase, and if yes - when to use rebase?" Considering
591 that it is very much recommended not to rebase published commits the
592 question's diminished even further: "whether to use rebase on
595 That small question is for the team to decide. To preserve the beauty
596 of linear history it's recommended to use rebase when pulling, i.e. do
597 ``git pull --rebase`` or even configure automatic setup of rebase for
600 $ git config branch.autosetuprebase always
602 and configure rebase for existing branches::
604 $ git config branch.$NAME.rebase true
608 $ git config branch.v1.rebase true
609 $ git config branch.master.rebase true
611 After that ``git pull origin master`` becomes equivalent to ``git pull
612 --rebase origin master``.
614 It is recommended to create new commits in a separate feature or topic
615 branch while using rebase to update the mainline branch. When the
616 topic branch is ready merge it into mainline. To avoid a tedious task
617 of resolving large number of conflicts at once you can merge the topic
618 branch to the mainline from time to time and switch back to the topic
619 branch to continue working on it. The entire workflow would be
622 $ git checkout -b issue-42 # create a new issue branch and switch to it
623 ...edit/test/commit...
624 $ git checkout master
625 $ git pull --rebase origin master # update master from the upstream
627 $ git branch -d issue-42 # delete the topic branch
628 $ git push origin master
630 When the topic branch is deleted only the label is removed, commits
631 are stayed in the database, they are now merged into master::
633 o--o--o--o--o--M--< master - the mainline branch
635 --*--*--* - the topic branch, now unnamed
637 The topic branch is deleted to avoid cluttering branch namespace with
638 small topic branches. Information on what issue was fixed or what
639 feature was implemented should be in the commit messages.
641 But even that small amount of rebasing could be too big in case of
642 long-lived merged branches. Imagine you're doing work in both ``v1``
643 and ``master`` branches, regularly merging ``v1`` into ``master``.
644 After some time you will have a lot of merge and non-merge commits in
645 ``master``. Then you want to push your finished work to a shared
646 repository and find someone has pushed a few commits to ``v1``. Now
647 you have a choice of two equally bad alternatives: either you fetch
648 and rebase ``v1`` and then have to recreate all you work in ``master``
649 (reset ``master`` to the origin, merge ``v1`` and cherry-pick all
650 non-merge commits from the old master); or merge the new ``v1`` and
651 loose the beauty of linear history.
657 Git has a builtin merge strategy for what Python core developers call
660 $ git merge -s ours v1 # null-merge v1 into master
666 Git doesn't assume any particular development model regarding
667 branching and merging. Some projects prefer to graduate patches from
668 the oldest branch to the newest, some prefer to cherry-pick commits
669 backwards, some use squashing (combining a number of commits into
670 one). Anything is possible.
672 There are a few examples to start with. `git help workflows
673 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_
674 describes how the very git authors develop git.
676 ProGit book has a few chapters devoted to branch management in
677 different projects: `Git Branching - Branching Workflows
678 <https://git-scm.com/book/en/Git-Branching-Branching-Workflows>`_ and
679 `Distributed Git - Contributing to a Project
680 <https://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project>`_.
682 There is also a well-known article `A successful Git branching model
683 <http://nvie.com/posts/a-successful-git-branching-model/>`_ by Vincent
684 Driessen. It recommends a set of very detailed rules on creating and
685 managing mainline, topic and bugfix branches. To support the model the
686 author implemented `git flow <https://github.com/nvie/gitflow>`_
690 Advanced configuration
691 ======================
696 Git has builtin mechanisms to handle line endings between platforms
697 with different end-of-line styles. To allow git to do CRLF conversion
698 assign ``text`` attribute to files using `.gitattributes
699 <https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
700 For files that have to have specific line endings assign ``eol``
701 attribute. For binary files the attribute is, naturally, ``binary``.
711 To check what attributes git uses for files use ``git check-attr``
712 command. For example::
714 $ git check-attr -a -- \*.py
720 `GitAlias <http://gitalias.com/>`_ (`repository
721 <https://github.com/GitAlias/gitalias>`_) is a big collection of
722 aliases. A careful selection of aliases for frequently used commands
723 could save you a lot of keystrokes!
725 `GitIgnore <https://www.gitignore.io/>`_ and
726 https://github.com/github/gitignore are collections of ``.gitignore``
727 files for all kinds of IDEs and programming languages. Python
730 `pre-commit <http://pre-commit.com/>`_ (`repositories
731 <https://github.com/pre-commit>`_) is a framework for managing and
732 maintaining multi-language pre-commit hooks. The framework is written
733 in Python and has a lot of plugins for many programming languages.
742 Staging area aka index aka cache is a distinguishing feature of git.
743 Staging area is where git collects patches before committing them.
744 Separation between collecting patches and commit phases provides a
745 very useful feature of git: you can review collected patches before
746 commit and even edit them - remove some hunks, add new hunks and
749 To add files to the index use ``git add``. Collecting patches before
750 committing means you need to do that for every change, not only to add
751 new (untracked) files. To simplify committing in case you just want to
752 commit everything without reviewing run ``git commit --all`` (or just
753 ``-a``) - the command adds every changed tracked file to the index and
754 then commit. To commit a file or files regardless of patches collected
755 in the index run ``git commit [--only|-o] -- $FILE...``.
757 To add hunks of patches to the index use ``git add --patch`` (or just
758 ``-p``). To remove collected files from the index use ``git reset HEAD
759 -- $FILE...`` To add/inspect/remove collected hunks use ``git add
760 --interactive`` (``-i``).
762 To see the diff between the index and the last commit (i.e., collected
763 patches) use ``git diff --cached``. To see the diff between the
764 working tree and the index (i.e., uncollected patches) use just ``git
765 diff``. To see the diff between the working tree and the last commit
766 (i.e., both collected and uncollected patches) run ``git diff HEAD``.
769 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
770 `IndexCommandQuickref
771 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
778 Git switches to the root (top-level directory of the project where
779 ``.git`` subdirectory exists) before running any command. Git
780 remembers though the directory that was current before the switch.
781 Some programs take into account the current directory. E.g., ``git
782 status`` shows file paths of changed and unknown files relative to the
783 current directory; ``git grep`` searches below the current directory;
784 ``git apply`` applies only those hunks from the patch that touch files
785 below the current directory.
787 But most commands run from the root and ignore the current directory.
788 Imagine, for example, that you have two work trees, one for the branch
789 ``v1`` and the other for ``master``. If you want to merge ``v1`` from
790 a subdirectory inside the second work tree you must write commands as
791 if you're in the top-level dir. Let take two work trees,
792 ``project-v1`` and ``project``, for example::
794 $ cd project/subdirectory
795 $ git fetch ../project-v1 v1:v1
798 Please note the path in ``git fetch ../project-v1 v1:v1`` is
799 ``../project-v1`` and not ``../../project-v1`` despite the fact that
800 we run the commands from a subdirectory, not from the root.
806 Rerere is a mechanism that helps to resolve repeated merge conflicts.
807 The most frequent source of recurring merge conflicts are topic
808 branches that are merged into mainline and then the merge commits are
809 removed; that's often performed to test the topic branches and train
810 rerere; merge commits are removed to have clean linear history and
811 finish the topic branch with only one last merge commit.
813 Rerere works by remembering the states of tree before and after a
814 successful commit. That way rerere can automatically resolve conflicts
815 if they appear in the same files.
817 Rerere can be used manually with ``git rerere`` command but most often
818 it's used automatically. Enable rerere with these commands in a
821 $ git config rerere.enabled true
822 $ git config rerere.autoupdate true
824 You don't need to turn rerere on globally - you don't want rerere in
825 bare repositories or single-branch repositories; you only need rerere
826 in repos where you often perform merges and resolve merge conflicts.
828 See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
835 Git object database and other files/directories under ``.git`` require
836 periodic maintenance and cleanup. For example, commit editing left
837 unreferenced objects (dangling objects, in git terminology) and these
838 objects should be pruned to avoid collecting cruft in the DB. The
839 command ``git gc`` is used for maintenance. Git automatically runs
840 ``git gc --auto`` as a part of some commands to do quick maintenance.
841 Users are recommended to run ``git gc --aggressive`` from time to
842 time; ``git help gc`` recommends to run it every few hundred
843 changesets; for more intensive projects it should be something like
844 once a week and less frequently (biweekly or monthly) for lesser
847 ``git gc --aggressive`` not only removes dangling objects, it also
848 repacks object database into indexed and better optimized pack(s); it
849 also packs symbolic references (branches and tags). Another way to do
850 it is to run ``git repack``.
852 There is a well-known `message
853 <https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html>`_ from Linus
854 Torvalds regarding "stupidity" of ``git gc --aggressive``. The message
855 can safely be ignored now. It is old and outdated, ``git gc
856 --aggressive`` became much better since that time.
858 For those who still prefer ``git repack`` over ``git gc --aggressive``
859 the recommended parameters are ``git repack -a -d -f --depth=20
860 --window=250``. See `this detailed experiment
861 <http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html>`_
862 for explanation of the effects of these parameters.
864 From time to time run ``git fsck [--strict]`` to verify integrity of
865 the database. ``git fsck`` may produce a list of dangling objects;
866 that's not an error, just a reminder to perform regular maintenance.
872 Command-line options and arguments
873 ----------------------------------
876 <https://www.kernel.org/pub/software/scm/git/docs/gitcli.html>`_
877 recommends not to combine short options/flags. Most of the times
878 combining works: ``git commit -av`` works perfectly, but there are
879 situations when it doesn't. E.g., ``git log -p -5`` cannot be combined
882 Some options have arguments, some even have default arguments. In that
883 case the argument for such option must be spelled in a sticky way:
884 ``-Oarg``, never ``-O arg`` because for an option that has a default
885 argument the latter means "use default value for option ``-O`` and
886 pass ``arg`` further to the option parser". For example, ``git grep``
887 has an option ``-O`` that passes a list of names of the found files to
888 a program; default program for ``-O`` is a pager (usually ``less``),
889 but you can use your editor::
891 $ git grep -Ovim # but not -O vim
893 BTW, if git is instructed to use ``less`` as the pager (i.e., if pager
894 is not configured in git at all it uses ``less`` by default, or if it
895 gets ``less`` from GIT_PAGER or PAGER environment variables, or if it
896 was configured with ``git config [--global] core.pager less``, or
897 ``less`` is used in the command ``git grep -Oless``) ``git grep``
898 passes ``+/$pattern`` option to ``less`` which is quite convenient.
899 Unfortunately, ``git grep`` doesn't pass the pattern if the pager is
900 not exactly ``less``, even if it's ``less`` with parameters (something
901 like ``git config [--global] core.pager less -FRSXgimq``); fortunately,
902 ``git grep -Oless`` always passes the pattern.
908 It's a bit hard to type ``git rebase --interactive --preserve-merges
909 HEAD~5`` manually even for those who are happy to use command-line,
910 and this is where shell completion is of great help. Bash/zsh come
911 with programmable completion, often automatically installed and
912 enabled, so if you have bash/zsh and git installed, chances are you
913 are already done - just go and use it at the command-line.
915 If you don't have necessary bits installed, install and enable
916 bash_completion package. If you want to upgrade your git completion to
917 the latest and greatest download necessary file from `git contrib
918 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion>`_.
920 Git-for-windows comes with git-bash for which bash completion is
921 installed and enabled.
927 For command-line lovers shell prompt can carry a lot of useful
928 information. To include git information in the prompt use
930 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion/git-prompt.sh>`_.
931 Read the detailed instructions in the file.
933 Search the Net for "git prompt" to find other prompt variants.
939 The simplest way to publish a repository or a group of repositories is
940 ``git daemon``. The daemon provides anonymous access, by default it is
941 read-only. The repositories are accessible by git protocol (git://
942 URLs). Write access can be enabled but the protocol lacks any
943 authentication means, so it should be enabled only within a trusted
944 LAN. See ``git help daemon`` for details.
946 Git over ssh provides authentication and repo-level authorisation as
947 repositories can be made user- or group-writeable (see parameter
948 ``core.sharedRepository`` in ``git help config``). If that's too
949 permissive or too restrictive for some project's needs there is a
950 wrapper `gitolite <http://gitolite.com/gitolite/index.html>`_ that can
951 be configured to allow access with great granularity; gitolite is
952 written in Perl and has a lot of documentation.
954 Web interface to browse repositories can be created using `gitweb
955 <https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ or `cgit
956 <http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
957 Perl and C). In addition to web interface both provide read-only dumb
958 http access for git (http(s):// URLs). `Klaus
959 <https://pypi.python.org/pypi/klaus>`_ is a small and simple WSGI web
960 server that implements both web interface and git smart HTTP
961 transport; supports Python 2 and Python 3, performs syntax
964 There are also more advanced web-based development environments that
965 include ability to manage users, groups and projects; private,
966 group-accessible and public repositories; they often include issue
967 trackers, wiki pages, pull requests and other tools for development
968 and communication. Among these environments are `Kallithea
969 <https://kallithea-scm.org/>`_ and `pagure <https://pagure.io/>`_,
970 both are written in Python; pagure was written by Fedora developers
971 and is being used to develop some Fedora projects. `GitPrep
972 <http://gitprep.yukikimoto.com/>`_ is yet another Github clone,
973 written in Perl. `Gogs <https://gogs.io/>`_ is written in Go.
974 `GitBucket <https://takezoe.github.io/gitbucket/about/>`_ is written
977 And last but not least, `Gitlab <https://about.gitlab.com/>`_. It's
978 perhaps the most advanced web-based development environment for git.
979 Written in Ruby, community edition is free and open source (MIT
983 From Mercurial to git
984 =====================
986 There are many tools to convert Mercurial repositories to git. The
987 most famous are, probably, `hg-git <https://hg-git.github.io/>`_ and
988 `fast-export <http://repo.or.cz/w/fast-export.git>`_ (many years ago
989 it was known under the name ``hg2git``).
991 But a better tool, perhaps the best, is `git-remote-hg
992 <https://github.com/felipec/git-remote-hg>`_. It provides transparent
993 bidirectional (pull and push) access to Mercurial repositories from
994 git. Its author wrote a `comparison of alternatives
995 <https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives>`_
996 that seems to be mostly objective.
998 To use git-remote-hg, install or clone it, add to your PATH (or copy
999 script ``git-remote-hg`` to a directory that's already in PATH) and
1000 prepend ``hg::`` to Mercurial URLs. For example::
1002 $ git clone https://github.com/felipec/git-remote-hg.git
1003 $ PATH=$PATH:"`pwd`"/git-remote-hg
1004 $ git clone hg::https://hg.python.org/peps/ PEPs
1006 To work with the repository just use regular git commands including
1007 ``git fetch/pull/push``.
1009 To start converting your Mercurial habits to git see the page
1010 `Mercurial for Git users
1011 <https://mercurial.selenic.com/wiki/GitConcepts>`_ at Mercurial wiki.
1012 At the second half of the page there is a table that lists
1013 corresponding Mercurial and git commands. Should work perfectly in
1016 Python Developer's Guide also has a chapter `Mercurial for git
1017 developers <https://docs.python.org/devguide/gitdevs.html>`_ that
1018 documents a few differences between git and hg.
1024 This document has been placed in the public domain.
1031 indent-tabs-mode: nil
1032 sentence-end-double-space: t
1036 vim: set fenc=us-ascii tw=70 :