6 This page (it was PEP 103) collects information about git. There is, of
7 course, a lot of documentation for git, so the PEP concentrates on
8 more complex (and more related to Python development) issues,
9 scenarios and examples.
15 Git is accompanied with a lot of documentation, both online and
19 Documentation for starters
20 --------------------------
23 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>`_,
25 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial-2.html>`_.
28 <https://www.kernel.org/pub/software/scm/git/docs/user-manual.html>`_.
29 `Everyday GIT With 20 Commands Or So
30 <https://www.kernel.org/pub/software/scm/git/docs/giteveryday.html>`_.
32 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
35 Advanced documentation
36 ----------------------
39 <http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html>`_,
40 with a number of translations.
42 `Pro Git <https://git-scm.com/book>`_. The Book about git. Buy it at
43 Amazon or download in PDF, mobi, or ePub form. It has translations to
44 many different languages. Download Russian translation from `GArik
45 <https://github.com/GArik/progit/wiki>`_.
47 `Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
49 `Git Buch <http://gitbu.ch/index.html>`_ (German).
55 Run ``git help $TOPIC``. For example, run ``git help git`` or
56 ``git help help``. Run ``git help -a`` to list help topics for all
57 available commands; ``git help -g`` to list help guides, i.e. help topics
64 Download and installation
65 -------------------------
67 Unix users: `download and install using your package manager
68 <https://git-scm.com/download/linux>`_.
70 Microsoft Windows: download `git-for-windows
71 <https://github.com/git-for-windows/git/releases>`_.
73 MacOS X: use git installed with `XCode
74 <https://developer.apple.com/xcode/>`_ or download from `MacPorts
75 <https://www.macports.org/ports.php?by=name&substr=git>`_ or
77 <http://sourceforge.net/projects/git-osx-installer/files/>`_ or
78 install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
80 `git-cola <https://git-cola.github.io/index.html>`_ (`repository
81 <https://github.com/git-cola/git-cola>`__) is a Git GUI written in
82 Python and GPL licensed. Linux, Windows, MacOS X.
84 `GitAhead <https://gitahead.com/>`_ is a completely free and open source
85 graphical Git client for Linux, Windows and macOS.
87 `TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
88 to Git based on TortoiseSVN; open source.
94 This simple code is often appears in documentation, but it is
95 important so let repeat it here. Git stores author and committer
96 names/emails in every commit, so configure your real name and
99 $ git config --global user.name "User Name"
100 $ git config --global user.email user.name@example.org
106 Examples of git commands in this PEP use the following approach. It is
107 supposed that you, the user, works with a local repository named
108 ``python`` that has an upstream remote repo named ``origin``. Your
109 local repo has two branches ``v1`` and ``master``. For most examples
110 the currently checked out branch is ``master``. That is, it's assumed
111 you have done something like that::
113 $ git clone https://git.python.org/python.git
115 $ git branch v1 origin/v1
117 The first command clones remote repository into local directory
118 `python``, creates a new local branch master, sets
119 remotes/origin/master as its upstream remote-tracking branch and
120 checks it out into the working directory.
122 The last command creates a new local branch v1 and sets
123 remotes/origin/v1 as its upstream remote-tracking branch.
125 The same result can be achieved with commands::
127 $ git clone -b v1 https://git.python.org/python.git
129 $ git checkout --track origin/master
131 The last command creates a new local branch master, sets
132 remotes/origin/master as its upstream remote-tracking branch and
133 checks it out into the working directory.
136 Branches and branches
137 =====================
139 Git terminology can be a bit misleading. Take, for example, the term
140 "branch". In git it has two meanings. A branch is a directed line of
141 commits (possibly with merges). And a branch is a label or a pointer
142 assigned to a line of commits. It is important to distinguish when you
143 talk about commits and when about their labels. Lines of commits are
144 by itself unnamed and are usually only lengthening and merging.
145 Labels, on the other hand, can be created, moved, renamed and deleted
149 Remote repositories and remote branches
150 =======================================
152 Remote-tracking branches are branches (pointers to commits) in your
153 local repository. They are there for git (and for you) to remember
154 what branches and commits have been pulled from and pushed to what
155 remote repos (you can pull from and push to many remotes).
156 Remote-tracking branches live under ``remotes/$REMOTE`` namespaces,
157 e.g. ``remotes/origin/master``.
159 To see the status of remote-tracking branches run::
163 To see local and remote-tracking branches (and tags) pointing to
168 You never do your own development on remote-tracking branches. You
169 create a local branch that has a remote branch as upstream and do
170 development on that local branch. On push git pushes commits to the
171 remote repo and updates remote-tracking branches, on pull git fetches
172 commits from the remote repo, updates remote-tracking branches and
173 fast-forwards, merges or rebases local branches.
175 When you do an initial clone like this::
177 $ git clone -b v1 https://git.python.org/python.git
179 git clones remote repository ``https://git.python.org/python.git`` to
180 directory ``python``, creates a remote named ``origin``, creates
181 remote-tracking branches, creates a local branch ``v1``, configure it
182 to track upstream remotes/origin/v1 branch and checks out ``v1`` into
183 the working directory.
185 Some commands, like ``git status --branch`` and ``git branch --verbose``,
186 report the difference between local and remote branches.
187 Please remember they only do comparison with remote-tracking branches
188 in your local repository, and the state of those remote-tracking
189 branches can be outdated. To update remote-tracking branches you
190 either fetch and merge (or rebase) commits from the remote repository
191 or update remote-tracking branches without updating local branches.
194 Updating local and remote-tracking branches
195 -------------------------------------------
197 To update remote-tracking branches without updating local branches run
198 ``git remote update [$REMOTE...]``. For example::
201 $ git remote update origin
207 There is a major difference between
211 $ git fetch $REMOTE $BRANCH
217 $ git fetch $REMOTE $BRANCH:$BRANCH
219 The first command fetches commits from the named $BRANCH in the
220 $REMOTE repository that are not in your repository, updates
221 remote-tracking branch and leaves the id (the hash) of the head commit
222 in file .git/FETCH_HEAD.
224 The second command fetches commits from the named $BRANCH in the
225 $REMOTE repository that are not in your repository and updates both
226 the local branch $BRANCH and its upstream remote-tracking branch. But
227 it refuses to update branches in case of non-fast-forward. And it
228 refuses to update the current branch (currently checked out branch,
229 where HEAD is pointing to).
231 The first command is used internally by ``git pull``.
235 $ git pull $REMOTE $BRANCH
241 $ git fetch $REMOTE $BRANCH
242 $ git merge FETCH_HEAD
244 Certainly, $BRANCH in that case should be your current branch. If you
245 want to merge a different branch into your current branch first update
246 that non-current branch and then merge::
248 $ git fetch origin v1:v1 # Update v1
249 $ git pull --rebase origin master # Update the current branch master
250 # using rebase instead of merge
253 If you have not yet pushed commits on ``v1``, though, the scenario has
254 to become a bit more complex. Git refuses to update
255 non-fast-forwardable branch, and you don't want to do force-pull
256 because that would remove your non-pushed commits and you would need
257 to recover. So you want to rebase ``v1`` but you cannot rebase
258 non-current branch. Hence, checkout ``v1`` and rebase it before
262 $ git pull --rebase origin v1
263 $ git checkout master
264 $ git pull --rebase origin master
267 It is possible to configure git to make it fetch/pull a few branches
268 or all branches at once, so you can simply run
280 Default remote repository for fetching/pulling is ``origin``. Default
281 set of references to fetch is calculated using matching algorithm: git
282 fetches all branches having the same name on both ends.
288 Pushing is a bit simpler. There is only one command ``push``. When you
293 $ git push origin v1 master
295 git pushes local v1 to remote v1 and local master to remote master.
298 $ git push origin v1:v1 master:master
300 Git pushes commits to the remote repo and updates remote-tracking
301 branches. Git refuses to push commits that aren't fast-forwardable.
302 You can force-push anyway, but please remember - you can force-push to
303 your own repositories but don't force-push to public or shared repos.
304 If you find git refuses to push commits that aren't fast-forwardable,
305 better fetch and merge commits from the remote repo (or rebase your
306 commits on top of the fetched commits), then push. Only force-push if
307 you know what you do and why you do it. See the section `Commit
308 editing and caveats`_ below.
310 It is possible to configure git to make it push a few branches or all
311 branches at once, so you can simply run
323 Default remote repository for pushing is ``origin``. Default set of
324 references to push in git before 2.0 is calculated using matching
325 algorithm: git pushes all branches having the same name on both ends.
326 Default set of references to push in git 2.0+ is calculated using
327 simple algorithm: git pushes the current branch back to its
330 To configure git before 2.0 to the new behaviour run::
332 $ git config push.default simple
334 To configure git 2.0+ to the old behaviour run::
336 $ git config push.default matching
338 Git doesn't allow to push a branch if it's the current branch in the
339 remote non-bare repository: git refuses to update remote working
340 directory. You really should push only to bare repositories. For
341 non-bare repositories git prefers pull-based workflow.
343 When you want to deploy code on a remote host and can only use push
344 (because your workstation is behind a firewall and you cannot pull
345 from it) you do that in two steps using two repositories: you push
346 from the workstation to a bare repo on the remote host, ssh to the
347 remote host and pull from the bare repo to a non-bare deployment repo.
349 That changed in git 2.3, but see `the blog post
350 <https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
351 for caveats; in 2.4 the push-to-deploy feature was `further improved
352 <https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
358 Git automatically fetches tags that point to commits being fetched
359 during fetch/pull. To fetch all tags (and commits they point to) run
360 ``git fetch --tags origin``. To fetch some specific tags fetch them
363 $ git fetch origin tag $TAG1 tag $TAG2...
367 $ git fetch origin tag 1.4.2
368 $ git fetch origin v1:v1 tag 2.1.7
370 Git doesn't automatically pushes tags. That allows you to have private
371 tags. To push tags list them explicitly::
373 $ git push origin tag 1.4.2
374 $ git push origin v1 master tag 2.1.7
376 Or push all tags at once::
378 $ git push --tags origin
380 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
381 after they have been published.
387 When cloning/fetching/pulling/pushing git copies only database objects
388 (commits, trees, files and tags) and symbolic references (branches and
389 lightweight tags). Everything else is private to the repository and
390 never cloned, updated or pushed. It's your config, your hooks, your
391 private exclude file.
393 If you want to distribute hooks, copy them to the working tree, add,
394 commit, push and instruct the team to update and install the hooks
398 Commit editing and caveats
399 ==========================
401 A warning not to edit published (pushed) commits also appears in
402 documentation but it's repeated here anyway as it's very important.
404 It is possible to recover from a forced push but it's PITA for the
405 entire team. Please avoid it.
407 To see what commits have not been published yet compare the head of the
408 branch with its upstream remote-tracking branch::
410 $ git log origin/master.. # from origin/master to HEAD (of master)
411 $ git log origin/v1..v1 # from origin/v1 to the head of v1
413 For every branch that has an upstream remote-tracking branch git
414 maintains an alias @{upstream} (short version @{u}), so the commands
415 above can be given as::
420 To see the status of all branches::
424 To compare the status of local branches with a remote repo::
426 $ git remote show origin
428 Read `how to recover from upstream rebase
429 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
430 It is in ``git help rebase``.
432 On the other hand, don't be too afraid about commit editing. You can
433 safely edit, reorder, remove, combine and split commits that haven't
434 been pushed yet. You can even push commits to your own (backup) repo,
435 edit them later and force-push edited commits to replace what have
436 already been pushed. Not a problem until commits are in a public
437 or shared repository.
443 Whatever you do, don't panic. Almost anything in git can be undone.
446 git checkout: restore file's content
447 ------------------------------------
449 ``git checkout``, for example, can be used to restore the content of
450 file(s) to that one of a commit. Like this::
452 git checkout HEAD~ README
454 The commands restores the contents of README file to the last but one
455 commit in the current branch. By default the commit ID is simply HEAD;
456 i.e. ``git checkout README`` restores README to the latest commit.
458 (Do not use ``git checkout`` to view a content of a file in a commit,
459 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
462 git reset: remove (non-pushed) commits
463 --------------------------------------
465 ``git reset`` moves the head of the current branch. The head can be
466 moved to point to any commit but it's often used to remove a commit or
467 a few (preferably, non-pushed ones) from the top of the branch - that
468 is, to move the branch backward in order to undo a few (non-pushed)
471 ``git reset`` has three modes of operation - soft, hard and mixed.
472 Default is mixed. ProGit `explains
473 <https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
474 difference very clearly. Bare repositories don't have indices or
475 working trees so in a bare repo only soft reset is possible.
481 Mixed mode reset with a path or paths can be used to unstage changes -
482 that is, to remove from index changes added with ``git add`` for
483 committing. See `The Book
484 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
485 about unstaging and other undo tricks.
488 git reflog: reference log
489 -------------------------
491 Removing commits with ``git reset`` or moving the head of a branch
492 sounds dangerous and it is. But there is a way to undo: another
493 reset back to the original commit. Git doesn't remove commits
494 immediately; unreferenced commits (in git terminology they are called
495 "dangling commits") stay in the database for some time (default is two
496 weeks) so you can reset back to it or create a new branch pointing to
499 For every move of a branch's head - with ``git commit``, ``git
500 checkout``, ``git fetch``, ``git pull``, ``git rebase``, ``git reset``
501 and so on - git stores a reference log (reflog for short). For every
502 move git stores where the head was. Command ``git reflog`` can be used
503 to view (and manipulate) the log.
505 In addition to the moves of the head of every branch git stores the
506 moves of the HEAD - a symbolic reference that (usually) names the
507 current branch. HEAD is changed with ``git checkout $BRANCH``.
509 By default ``git reflog`` shows the moves of the HEAD, i.e. the
510 command is equivalent to ``git reflog HEAD``. To show the moves of the
511 head of a branch use the command ``git reflog $BRANCH``.
513 So to undo a ``git reset`` lookup the original commit in ``git
514 reflog``, verify it with ``git show`` or ``git log`` and run ``git
515 reset $COMMIT_ID``. Git stores the move of the branch's head in
516 reflog, so you can undo that undo later again.
518 In a more complex situation you'd want to move some commits along with
519 resetting the head of the branch. Cherry-pick them to the new branch.
520 For example, if you want to reset the branch ``master`` back to the
521 original commit but preserve two commits created in the current branch
524 $ git branch save-master # create a new branch saving master
525 $ git reflog # find the original place of master
526 $ git reset $COMMIT_ID
527 $ git cherry-pick save-master~ save-master
528 $ git branch -D save-master # remove temporary branch
531 git revert: revert a commit
532 ---------------------------
534 ``git revert`` reverts a commit or commits, that is, it creates a new
535 commit or commits that revert(s) the effects of the given commits.
536 It's the only way to undo published commits (``git commit --amend``,
537 ``git rebase`` and ``git reset`` change the branch in
538 non-fast-forwardable ways so they should only be used for non-pushed
541 There is a problem with reverting a merge commit. ``git revert`` can
542 undo the code created by the merge commit but it cannot undo the fact
543 of merge. See the discussion `How to revert a faulty merge
544 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
547 One thing that cannot be undone
548 -------------------------------
550 Whatever you undo, there is one thing that cannot be undone -
551 overwritten uncommitted changes. Uncommitted changes don't belong to
552 git so git cannot help preserving them.
554 Most of the time git warns you when you're going to execute a command
555 that overwrites uncommitted changes. Git doesn't allow you to switch
556 branches with ``git checkout``. It stops you when you're going to
557 rebase with non-clean working tree. It refuses to pull new commits
558 over non-committed files.
560 But there are commands that do exactly that - overwrite files in the
561 working tree. Commands like ``git checkout $PATHs`` or ``git reset
562 --hard`` silently overwrite files including your uncommitted changes.
564 With that in mind you can understand the stance "commit early, commit
565 often". Commit as often as possible. Commit on every save in your
566 editor or IDE. You can edit your commits before pushing - edit commit
567 messages, change commits, reorder, combine, split, remove. But save
568 your changes in git database, either commit changes or at least stash
569 them with ``git stash``.
575 Internet is full of heated discussions on the topic: "merge or
576 rebase?" Most of them are meaningless. When a DVCS is being used in a
577 big team with a big and complex project with many branches there is
578 simply no way to avoid merges. So the question's diminished to
579 "whether to use rebase, and if yes - when to use rebase?" Considering
580 that it is very much recommended not to rebase published commits the
581 question's diminished even further: "whether to use rebase on
584 That small question is for the team to decide. To preserve the beauty
585 of linear history it's recommended to use rebase when pulling, i.e. do
586 ``git pull --rebase`` or even configure automatic setup of rebase for
589 $ git config branch.autosetuprebase always
591 and configure rebase for existing branches::
593 $ git config branch.$NAME.rebase true
597 $ git config branch.v1.rebase true
598 $ git config branch.master.rebase true
600 After that ``git pull origin master`` becomes equivalent to ``git pull
601 --rebase origin master``.
603 It is recommended to create new commits in a separate feature or topic
604 branch while using rebase to update the mainline branch. When the
605 topic branch is ready merge it into mainline. To avoid a tedious task
606 of resolving large number of conflicts at once you can merge the topic
607 branch to the mainline from time to time and switch back to the topic
608 branch to continue working on it. The entire workflow would be
611 $ git checkout -b issue-42 # create a new issue branch and switch to it
612 ...edit/test/commit...
613 $ git checkout master
614 $ git pull --rebase origin master # update master from the upstream
616 $ git branch -d issue-42 # delete the topic branch
617 $ git push origin master
619 When the topic branch is deleted only the label is removed, commits
620 are stayed in the database, they are now merged into master::
622 o--o--o--o--o--M--< master - the mainline branch
624 --*--*--* - the topic branch, now unnamed
626 The topic branch is deleted to avoid cluttering branch namespace with
627 small topic branches. Information on what issue was fixed or what
628 feature was implemented should be in the commit messages.
630 But even that small amount of rebasing could be too big in case of
631 long-lived merged branches. Imagine you're doing work in both ``v1``
632 and ``master`` branches, regularly merging ``v1`` into ``master``.
633 After some time you will have a lot of merge and non-merge commits in
634 ``master``. Then you want to push your finished work to a shared
635 repository and find someone has pushed a few commits to ``v1``. Now
636 you have a choice of two equally bad alternatives: either you fetch
637 and rebase ``v1`` and then have to recreate all you work in ``master``
638 (reset ``master`` to the origin, merge ``v1`` and cherry-pick all
639 non-merge commits from the old master); or merge the new ``v1`` and
640 loose the beauty of linear history.
646 Git has a builtin merge strategy for what Python core developers call
649 $ git merge -s ours v1 # null-merge v1 into master
655 Git doesn't assume any particular development model regarding
656 branching and merging. Some projects prefer to graduate patches from
657 the oldest branch to the newest, some prefer to cherry-pick commits
658 backwards, some use squashing (combining a number of commits into
659 one). Anything is possible.
661 There are a few examples to start with. `git help workflows
662 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_
663 describes how the very git authors develop git.
665 ProGit book has a few chapters devoted to branch management in
666 different projects: `Git Branching - Branching Workflows
667 <https://git-scm.com/book/en/Git-Branching-Branching-Workflows>`_ and
668 `Distributed Git - Contributing to a Project
669 <https://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project>`_.
671 There is also a well-known article `A successful Git branching model
672 <http://nvie.com/posts/a-successful-git-branching-model/>`_ by Vincent
673 Driessen. It recommends a set of very detailed rules on creating and
674 managing mainline, topic and bugfix branches. To support the model the
675 author implemented `git flow <https://github.com/nvie/gitflow>`_
679 Advanced configuration
680 ======================
685 Git has builtin mechanisms to handle line endings between platforms
686 with different end-of-line styles. To allow git to do CRLF conversion
687 assign ``text`` attribute to files using `.gitattributes
688 <https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
689 For files that have to have specific line endings assign ``eol``
690 attribute. For binary files the attribute is, naturally, ``binary``.
700 To check what attributes git uses for files use ``git check-attr``
701 command. For example::
703 $ git check-attr -a -- \*.py
709 `GitAlias <http://gitalias.com/>`_ (`repository
710 <https://github.com/GitAlias/gitalias>`_) is a big collection of
711 aliases. A careful selection of aliases for frequently used commands
712 could save you a lot of keystrokes!
714 `GitIgnore <https://www.gitignore.io/>`_ and
715 https://github.com/github/gitignore are collections of ``.gitignore``
716 files for all kinds of IDEs and programming languages. Python
719 `pre-commit <http://pre-commit.com/>`_ (`repositories
720 <https://github.com/pre-commit>`_) is a framework for managing and
721 maintaining multi-language pre-commit hooks. The framework is written
722 in Python and has a lot of plugins for many programming languages.
731 Staging area aka index aka cache is a distinguishing feature of git.
732 Staging area is where git collects patches before committing them.
733 Separation between collecting patches and commit phases provides a
734 very useful feature of git: you can review collected patches before
735 commit and even edit them - remove some hunks, add new hunks and
738 To add files to the index use ``git add``. Collecting patches before
739 committing means you need to do that for every change, not only to add
740 new (untracked) files. To simplify committing in case you just want to
741 commit everything without reviewing run ``git commit --all`` (or just
742 ``-a``) - the command adds every changed tracked file to the index and
743 then commit. To commit a file or files regardless of patches collected
744 in the index run ``git commit [--only|-o] -- $FILE...``.
746 To add hunks of patches to the index use ``git add --patch`` (or just
747 ``-p``). To remove collected files from the index use ``git reset HEAD
748 -- $FILE...`` To add/inspect/remove collected hunks use ``git add
749 --interactive`` (``-i``).
751 To see the diff between the index and the last commit (i.e., collected
752 patches) use ``git diff --cached``. To see the diff between the
753 working tree and the index (i.e., uncollected patches) use just ``git
754 diff``. To see the diff between the working tree and the last commit
755 (i.e., both collected and uncollected patches) run ``git diff HEAD``.
758 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
759 `IndexCommandQuickref
760 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
770 Git doesn't allow recursive aliases. The expansion of an alias is
771 interpreted by git as a builtin command. I.e., in the following example
772 alias ``com`` doesn't work because there is no builtin command ``git
779 You can trick git by using shell. The following example works albeit a
790 Git interprets aliases literally. I.e., when expanding an alias git just
791 does simple textual substitution. That could be a surprise if an alias
792 is passed parameters on the command line. For example, the following
793 alias works without parameters -- it pushes configured branch(es) to all
797 push-to-all-remotes = !git remote | xargs -n1 git push
799 But it doesn't work if a user wants to provide a list of branches to
800 push: the command ``git push-to-all-remotes master`` is expanded by git
801 as ``!git remote | xargs -n1 git push master`` which is certainly not
802 what the user wants -- remote's name must comes first, before branches.
806 push-to-all-remotes = !git remote | xargs -I% -n1 git push %
808 Then the command ``git push-to-all-remotes master`` is expanded by git
809 as ``!git remote | xargs -I% -n1 git push % master``; xargs substitutes
810 ``%`` with remote's name.
816 Git switches to the root (top-level directory of the project where
817 ``.git`` subdirectory exists) before running any command. Git
818 remembers though the directory that was current before the switch.
819 Some programs take into account the current directory. E.g., ``git
820 status`` shows file paths of changed and unknown files relative to the
821 current directory; ``git grep`` searches below the current directory;
822 ``git apply`` applies only those hunks from the patch that touch files
823 below the current directory.
825 But most commands run from the root and ignore the current directory.
826 Imagine, for example, that you have two work trees, one for the branch
827 ``v1`` and the other for ``master``. If you want to merge ``v1`` from
828 a subdirectory inside the second work tree you must write commands as
829 if you're in the top-level dir. Let take two work trees,
830 ``project-v1`` and ``project``, for example::
832 $ cd project/subdirectory
833 $ git fetch ../project-v1 v1:v1
836 Please note the path in ``git fetch ../project-v1 v1:v1`` is
837 ``../project-v1`` and not ``../../project-v1`` despite the fact that
838 we run the commands from a subdirectory, not from the root.
844 Rerere is a mechanism that helps to resolve repeated merge conflicts.
845 The most frequent source of recurring merge conflicts are topic
846 branches that are merged into mainline and then the merge commits are
847 removed; that's often performed to test the topic branches and train
848 rerere; merge commits are removed to have clean linear history and
849 finish the topic branch with only one last merge commit.
851 Rerere works by remembering the states of tree before and after a
852 successful commit. That way rerere can automatically resolve conflicts
853 if they appear in the same files.
855 Rerere can be used manually with ``git rerere`` command but most often
856 it's used automatically. Enable rerere with these commands in a
859 $ git config rerere.enabled true
860 $ git config rerere.autoupdate true
862 You don't need to turn rerere on globally - you don't want rerere in
863 bare repositories or single-branch repositories; you only need rerere
864 in repos where you often perform merges and resolve merge conflicts.
866 See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
873 Git object database and other files/directories under ``.git`` require
874 periodic maintenance and cleanup. For example, commit editing left
875 unreferenced objects (dangling objects, in git terminology) and these
876 objects should be pruned to avoid collecting cruft in the DB. The
877 command ``git gc`` is used for maintenance. Git automatically runs
878 ``git gc --auto`` as a part of some commands to do quick maintenance.
879 Users are recommended to run ``git gc --aggressive`` from time to
880 time; ``git help gc`` recommends to run it every few hundred
881 changesets; for more intensive projects it should be something like
882 once a week and less frequently (biweekly or monthly) for lesser
885 ``git gc --aggressive`` not only removes dangling objects, it also
886 repacks object database into indexed and better optimized pack(s); it
887 also packs symbolic references (branches and tags). Another way to do
888 it is to run ``git repack``.
890 There is a well-known `message
891 <https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html>`_ from Linus
892 Torvalds regarding "stupidity" of ``git gc --aggressive``. The message
893 can safely be ignored now. It is old and outdated, ``git gc
894 --aggressive`` became much better since that time.
896 For those who still prefer ``git repack`` over ``git gc --aggressive``
897 the recommended parameters are ``git repack -a -d -f --depth=20
898 --window=250``. See `this detailed experiment
899 <http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html>`_
900 for explanation of the effects of these parameters.
902 From time to time run ``git fsck [--strict]`` to verify integrity of
903 the database. ``git fsck`` may produce a list of dangling objects;
904 that's not an error, just a reminder to perform regular maintenance.
910 Command-line options and arguments
911 ----------------------------------
914 <https://www.kernel.org/pub/software/scm/git/docs/gitcli.html>`_
915 recommends not to combine short options/flags. Most of the times
916 combining works: ``git commit -av`` works perfectly, but there are
917 situations when it doesn't. E.g., ``git log -p -5`` cannot be combined
920 Some options have arguments, some even have default arguments. In that
921 case the argument for such option must be spelled in a sticky way:
922 ``-Oarg``, never ``-O arg`` because for an option that has a default
923 argument the latter means "use default value for option ``-O`` and
924 pass ``arg`` further to the option parser". For example, ``git grep``
925 has an option ``-O`` that passes a list of names of the found files to
926 a program; default program for ``-O`` is a pager (usually ``less``),
927 but you can use your editor::
929 $ git grep -Ovim # but not -O vim
931 BTW, if git is instructed to use ``less`` as the pager (i.e., if pager
932 is not configured in git at all it uses ``less`` by default, or if it
933 gets ``less`` from GIT_PAGER or PAGER environment variables, or if it
934 was configured with ``git config [--global] core.pager less``, or
935 ``less`` is used in the command ``git grep -Oless``) ``git grep``
936 passes ``+/$pattern`` option to ``less`` which is quite convenient.
937 Unfortunately, ``git grep`` doesn't pass the pattern if the pager is
938 not exactly ``less``, even if it's ``less`` with parameters (something
939 like ``git config [--global] core.pager less -FRSXgimq``); fortunately,
940 ``git grep -Oless`` always passes the pattern.
946 It's a bit hard to type ``git rebase --interactive --preserve-merges
947 HEAD~5`` manually even for those who are happy to use command-line,
948 and this is where shell completion is of great help. Bash/zsh come
949 with programmable completion, often automatically installed and
950 enabled, so if you have bash/zsh and git installed, chances are you
951 are already done - just go and use it at the command-line.
953 If you don't have necessary bits installed, install and enable
954 bash_completion package. If you want to upgrade your git completion to
955 the latest and greatest download necessary file from `git contrib
956 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion>`_.
958 Git-for-windows comes with git-bash for which bash completion is
959 installed and enabled.
965 For command-line lovers shell prompt can carry a lot of useful
966 information. To include git information in the prompt use
968 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion/git-prompt.sh>`_.
969 Read the detailed instructions in the file.
971 Search the Net for "git prompt" to find other prompt variants.
974 SSH connection sharing
975 ----------------------
977 SSH connection sharing is a feature of OpenSSH and perhaps derivatives
978 like PuTTY. SSH connection sharing is a way to decrease ssh client
979 startup time by establishing one connection and reusing it for all
980 subsequent clients connecting to the same server. SSH connection
981 sharing can be used to speedup a lot of short ssh sessions like scp,
982 sftp, rsync and of course git over ssh. If you regularly
983 fetch/pull/push from/to remote repositories accessible over ssh then
984 using ssh connection sharing is recommended.
986 To turn on ssh connection sharing add something like this to your
991 ControlPath ~/.ssh/mux-%r@%h:%p
994 See `OpenSSH wikibook
995 <https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing>`_ and
996 `search <https://www.google.com/search?q=ssh+connection+sharing>`_ for
999 SSH connection sharing can be used at GitHub, GitLab and SourceForge
1000 repositories, but please be advised that BitBucket doesn't allow it
1001 and forcibly closes master connection after a short inactivity period
1002 so you will see errors like this from ssh: "Connection to bitbucket.org
1003 closed by remote host."
1009 The simplest way to publish a repository or a group of repositories is
1010 ``git daemon``. The daemon provides anonymous access, by default it is
1011 read-only. The repositories are accessible by git protocol (git://
1012 URLs). Write access can be enabled but the protocol lacks any
1013 authentication means, so it should be enabled only within a trusted
1014 LAN. See ``git help daemon`` for details.
1016 Git over ssh provides authentication and repo-level authorisation as
1017 repositories can be made user- or group-writeable (see parameter
1018 ``core.sharedRepository`` in ``git help config``). If that's too
1019 permissive or too restrictive for some project's needs there is a
1020 wrapper `gitolite <http://gitolite.com/gitolite/index.html>`_ that can
1021 be configured to allow access with great granularity; gitolite is
1022 written in Perl and has a lot of documentation.
1024 Web interface to browse repositories can be created using `gitweb
1025 <https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ or `cgit
1026 <http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
1027 Perl and C). In addition to web interface both provide read-only dumb
1028 http access for git (http(s):// URLs). `Klaus
1029 <https://pypi.org/project/klaus/>`_ is a small and simple WSGI web
1030 server that implements both web interface and git smart HTTP
1031 transport; supports Python 2 and Python 3, performs syntax
1034 There are also more advanced web-based development environments that
1035 include ability to manage users, groups and projects; private,
1036 group-accessible and public repositories; they often include issue
1037 trackers, wiki pages, pull requests and other tools for development
1038 and communication. Among these environments are `Kallithea
1039 <https://kallithea-scm.org/>`_ and `pagure <https://pagure.io/>`_,
1040 both are written in Python; pagure was written by Fedora developers
1041 and is being used to develop some Fedora projects. `GitPrep
1042 <http://gitprep.yukikimoto.com/>`_ is yet another GitHub clone,
1043 written in Perl. `Gogs <https://gogs.io/>`_ is written in Go. `GitBucket
1044 <https://gitbucket.github.io/gitbucket-news/about/>`_ is written in
1045 Scala. `RocketGit <https://rocketgit.com/>`_ is AGPL-licensed
1046 development environment written in PHP (there are plans to rewrite
1047 critical parts in C).
1049 And last but not least, `GitLab <https://about.gitlab.com/>`_. It's
1050 perhaps the most advanced web-based development environment for git.
1051 Written in Ruby, community edition is free and open source (MIT
1055 From Mercurial to git
1056 =====================
1058 There are many tools to convert Mercurial repositories to git. The
1059 most famous are, probably, `hg-git <https://hg-git.github.io/>`_ and
1060 `fast-export <http://repo.or.cz/w/fast-export.git>`_ (many years ago
1061 it was known under the name ``hg2git``).
1063 But a better tool, perhaps the best, is `git-remote-hg
1064 <https://github.com/felipec/git-remote-hg>`_. It provides transparent
1065 bidirectional (pull and push) access to Mercurial repositories from
1066 git. Its author wrote a `comparison of alternatives
1067 <https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives>`_
1068 that seems to be mostly objective.
1070 To use git-remote-hg, install or clone it, add to your PATH (or copy
1071 script ``git-remote-hg`` to a directory that's already in PATH) and
1072 prepend ``hg::`` to Mercurial URLs. For example::
1074 $ git clone https://github.com/felipec/git-remote-hg.git
1075 $ PATH=$PATH:"`pwd`"/git-remote-hg
1076 $ git clone hg::https://hg.python.org/peps/ PEPs
1078 To work with the repository just use regular git commands including
1079 ``git fetch/pull/push``.
1081 To start converting your Mercurial habits to git see the page
1082 `Mercurial for Git users
1083 <https://www.mercurial-scm.org/wiki/GitConcepts>`_ at Mercurial wiki.
1084 At the second half of the page there is a table that lists
1085 corresponding Mercurial and git commands. Should work perfectly in
1088 Python Developer's Guide also has a chapter `Mercurial for git
1089 developers <https://docs.python.org/devguide/gitdevs.html>`_ that
1090 documents a few differences between git and hg.
1096 `gitsome <https://github.com/donnemartin/gitsome>`_ - Git/GitHub
1097 command line interface (CLI). Written in Python, work on MacOS, Unix,
1098 Windows. Git/GitHub CLI with autocomplete, includes many GitHub
1099 integrated commands that work with all shells, builtin xonsh with
1100 Python REPL to run Python commands alongside shell commands, command
1101 history, customizable highlighting, thoroughly documented.