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.
197 Updating local and remote-tracking branches
198 -------------------------------------------
200 There is a major difference between
204 $ git fetch $REMOTE $BRANCH
210 $ git fetch $REMOTE $BRANCH:$BRANCH
212 The first command fetches commits from the named $BRANCH in the
213 $REMOTE repository that are not in your repository, updates
214 remote-tracking branch and leaves the id (the hash) of the head commit
215 in file .git/FETCH_HEAD.
217 The second command fetches commits from the named $BRANCH in the
218 $REMOTE repository that are not in your repository and updates both
219 the local branch $BRANCH and its upstream remote-tracking branch. But
220 it refuses to update branches in case of non-fast-forward. And it
221 refuses to update the current branch (currently checked out branch,
222 where HEAD is pointing to).
224 The first command is used internally by ``git pull``.
228 $ git pull $REMOTE $BRANCH
234 $ git fetch $REMOTE $BRANCH
235 $ git merge FETCH_HEAD
237 Certainly, $BRANCH in that case should be your current branch. If you
238 want to merge a different branch into your current branch first update
239 that non-current branch and then merge::
241 $ git fetch origin v1:v1 # Update v1
242 $ git pull --rebase origin master # Update the current branch master
243 # using rebase instead of merge
246 If you have not yet pushed commits on ``v1``, though, the scenario has
247 to become a bit more complex. Git refuses to update
248 non-fast-forwardable branch, and you don't want to do force-pull
249 because that would remove your non-pushed commits and you would need
250 to recover. So you want to rebase ``v1`` but you cannot rebase
251 non-current branch. Hence, checkout ``v1`` and rebase it before
255 $ git pull --rebase origin v1
256 $ git checkout master
257 $ git pull --rebase origin master
260 It is possible to configure git to make it fetch/pull a few branches
261 or all branches at once, so you can simply run
273 Default remote repository for fetching/pulling is ``origin``. Default
274 set of references to fetch is calculated using matching algorithm: git
275 fetches all branches having the same name on both ends.
281 Pushing is a bit simpler. There is only one command ``push``. When you
286 $ git push origin v1 master
288 git pushes local v1 to remote v1 and local master to remote master.
291 $ git push origin v1:v1 master:master
293 Git pushes commits to the remote repo and updates remote-tracking
294 branches. Git refuses to push commits that aren't fast-forwardable.
295 You can force-push anyway, but please remember - you can force-push to
296 your own repositories but don't force-push to public or shared repos.
297 If you find git refuses to push commits that aren't fast-forwardable,
298 better fetch and merge commits from the remote repo (or rebase your
299 commits on top of the fetched commits), then push. Only force-push if
300 you know what you do and why you do it. See the section `Commit
301 editing and caveats`_ below.
303 It is possible to configure git to make it push a few branches or all
304 branches at once, so you can simply run
316 Default remote repository for pushing is ``origin``. Default set of
317 references to push in git before 2.0 is calculated using matching
318 algorithm: git pushes all branches having the same name on both ends.
319 Default set of references to push in git 2.0+ is calculated using
320 simple algorithm: git pushes the current branch back to its
323 To configure git before 2.0 to the new behaviour run::
325 $ git config push.default simple
327 To configure git 2.0+ to the old behaviour run::
329 $ git config push.default matching
331 Git doesn't allow to push a branch if it's the current branch in the
332 remote non-bare repository: git refuses to update remote working
333 directory. You really should push only to bare repositories. For
334 non-bare repositories git prefers pull-based workflow.
336 When you want to deploy code on a remote host and can only use push
337 (because your workstation is behind a firewall and you cannot pull
338 from it) you do that in two steps using two repositories: you push
339 from the workstation to a bare repo on the remote host, ssh to the
340 remote host and pull from the bare repo to a non-bare deployment repo.
342 That changed in git 2.3, but see `the blog post
343 <https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
344 for caveats; in 2.4 the push-to-deploy feature was `further improved
345 <https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
351 Git automatically fetches tags that point to commits being fetched
352 during fetch/pull. To fetch all tags (and commits they point to) run
353 ``git fetch --tags origin``. To fetch some specific tags fetch them
356 $ git fetch origin tag $TAG1 tag $TAG2...
360 $ git fetch origin tag 1.4.2
361 $ git fetch origin v1:v1 tag 2.1.7
363 Git doesn't automatically pushes tags. That allows you to have private
364 tags. To push tags list them explicitly::
366 $ git push origin tag 1.4.2
367 $ git push origin v1 master tag 2.1.7
369 Or push all tags at once::
371 $ git push --tags origin
373 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
374 after they have been published.
380 When cloning/fetching/pulling/pushing git copies only database objects
381 (commits, trees, files and tags) and symbolic references (branches and
382 lightweight tags). Everything else is private to the repository and
383 never cloned, updated or pushed. It's your config, your hooks, your
384 private exclude file.
386 If you want to distribute hooks, copy them to the working tree, add,
387 commit, push and instruct the team to update and install the hooks
391 Commit editing and caveats
392 ==========================
394 A warning not to edit published (pushed) commits also appears in
395 documentation but it's repeated here anyway as it's very important.
397 It is possible to recover from a forced push but it's PITA for the
398 entire team. Please avoid it.
400 To see what commits have not been published yet compare the head of the
401 branch with its upstream remote-tracking branch::
403 $ git log origin/master.. # from origin/master to HEAD (of master)
404 $ git log origin/v1..v1 # from origin/v1 to the head of v1
406 For every branch that has an upstream remote-tracking branch git
407 maintains an alias @{upstream} (short version @{u}), so the commands
408 above can be given as::
413 To see the status of all branches::
417 To compare the status of local branches with a remote repo::
419 $ git remote show origin
421 Read `how to recover from upstream rebase
422 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
423 It is in ``git help rebase``.
425 On the other hand don't be too afraid about commit editing. You can
426 safely edit, reorder, remove, combine and split commits that haven't
427 been pushed yet. You can even push commits to your own (backup) repo,
428 edit them later and force-push edited commits to replace what have
429 already been pushed. Not a problem until commits are in a public
430 or shared repository.
436 Whatever you do, don't panic. Almost anything in git can be undone.
439 git checkout: restore file's content
440 ------------------------------------
442 ``git checkout``, for example, can be used to restore the content of
443 file(s) to that one of a commit. Like this::
445 git checkout HEAD~ README
447 The commands restores the contents of README file to the last but one
448 commit in the current branch. By default the commit ID is simply HEAD;
449 i.e. ``git checkout README`` restores README to the latest commit.
451 (Do not use ``git checkout`` to view a content of a file in a commit,
452 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
455 git reset: remove (non-pushed) commits
456 --------------------------------------
458 ``git reset`` moves the head of the current branch. The head can be
459 moved to point to any commit but it's often used to remove a commit or
460 a few (preferably, non-pushed ones) from the top of the branch - that
461 is, to move the branch backward in order to undo a few (non-pushed)
464 ``git reset`` has three modes of operation - soft, hard and mixed.
465 Default is mixed. ProGit `explains
466 <https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
467 difference very clearly. Bare repositories don't have indices or
468 working trees so in a bare repo only soft reset is possible.
474 Mixed mode reset with a path or paths can be used to unstage changes -
475 that is, to remove from index changes added with ``git add`` for
476 committing. See `The Book
477 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
478 about unstaging and other undo tricks.
481 git reflog: reference log
482 -------------------------
484 Removing commits with ``git reset`` or moving the head of a branch
485 sounds dangerous and it is. But there is a way to undo: another
486 reset back to the original commit. Git doesn't remove commits
487 immediately; unreferenced commits (in git terminology they are called
488 "dangling commits") stay in the database for some time (default is two
489 weeks) so you can reset back to it or create a new branch pointing to
492 For every move of a branch's head - with ``git commit``, ``git
493 checkout``, ``git fetch``, ``git pull``, ``git rebase``, ``git reset``
494 and so on - git stores a reference log (reflog for short). For every
495 move git stores where the head was. Command ``git reflog`` can be used
496 to view (and manipulate) the log.
498 In addition to the moves of the head of every branch git stores the
499 moves of the HEAD - a symbolic reference that (usually) names the
500 current branch. HEAD is changed with ``git checkout $BRANCH``.
502 By default ``git reflog`` shows the moves of the HEAD, i.e. the
503 command is equivalent to ``git reflog HEAD``. To show the moves of the
504 head of a branch use the command ``git reflog $BRANCH``.
506 So to undo a ``git reset`` lookup the original commit in ``git
507 reflog``, verify it with ``git show`` or ``git log`` and run ``git
508 reset $COMMIT_ID``. Git stores the move of the branch's head in
509 reflog, so you can undo that undo later again.
511 In a more complex situation you'd want to move some commits along with
512 resetting the head of the branch. Cherry-pick them to the new branch.
513 For example, if you want to reset the branch ``master`` back to the
514 original commit but preserve two commits created in the current branch
517 $ git branch save-master # create a new branch saving master
518 $ git reflog # find the original place of master
519 $ git reset $COMMIT_ID
520 $ git cherry-pick save-master~ save-master
521 $ git branch -D save-master # remove temporary branch
524 git revert: revert a commit
525 ---------------------------
527 ``git revert`` reverts a commit or commits, that is, it creates a new
528 commit or commits that revert(s) the effects of the given commits.
529 It's the only way to undo published commits (``git commit --amend``,
530 ``git rebase`` and ``git reset`` change the branch in
531 non-fast-forwardable ways so they should only be used for non-pushed
534 There is a problem with reverting a merge commit. ``git revert`` can
535 undo the code created by the merge commit but it cannot undo the fact
536 of merge. See the discussion `How to revert a faulty merge
537 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
540 One thing that cannot be undone
541 -------------------------------
543 Whatever you undo, there is one thing that cannot be undone -
544 overwritten uncommitted changes. Uncommitted changes don't belong to
545 git so git cannot help preserving them.
547 Most of the time git warns you when you're going to execute a command
548 that overwrites uncommitted changes. Git doesn't allow you to switch
549 branches with ``git checkout``. It stops you when you're going to
550 rebase with non-clean working tree. It refuses to pull new commits
551 over non-committed files.
553 But there are commands that do exactly that - overwrite files in the
554 working tree. Commands like ``git checkout $PATHs`` or ``git reset
555 --hard`` silently overwrite files including your uncommitted changes.
557 With that in mind you can understand the stance "commit early, commit
558 often". Commit as often as possible. Commit on every save in your
559 editor or IDE. You can edit your commits before pushing - edit commit
560 messages, change commits, reorder, combine, split, remove. But save
561 your changes in git database, either commit changes or at least stash
562 them with ``git stash``.
568 Internet is full of heated discussions on the topic: "merge or
569 rebase?" Most of them are meaningless. When a DVCS is being used in a
570 big team with a big and complex project with many branches there is
571 simply no way to avoid merges. So the question's diminished to
572 "whether to use rebase, and if yes - when to use rebase?" Considering
573 that it is very much recommended not to rebase published commits the
574 question's diminished even further: "whether to use rebase on
577 That small question is for the team to decide. The author of the PEP
578 recommends to use rebase when pulling, i.e. always do ``git pull
579 --rebase`` or even configure automatic setup of rebase for every new
582 $ git config branch.autosetuprebase always
584 and configure rebase for existing branches::
586 $ git config branch.$NAME.rebase true
590 $ git config branch.v1.rebase true
591 $ git config branch.master.rebase true
593 After that ``git pull origin master`` becomes equivalent to ``git pull
594 --rebase origin master``.
596 It is recommended to create new commits in a separate feature or topic
597 branch while using rebase to update the mainline branch. When the
598 topic branch is ready merge it into mainline. To avoid a tedious task
599 of resolving large number of conflicts at once you can merge the topic
600 branch to the mainline from time to time and switch back to the topic
601 branch to continue working on it. The entire workflow would be
604 $ git checkout -b issue-42 # create a new issue branch and switch to it
605 ...edit/test/commit...
606 $ git checkout master
607 $ git pull --rebase origin master # update master from the upstream
609 $ git branch -d issue-42 # delete the topic branch
610 $ git push origin master
612 When the topic branch is deleted only the label is removed, commits
613 are stayed in the database, they are now merged into master::
615 o--o--o--o--o--M--< master - the mainline branch
617 --*--*--* - the topic branch, now unnamed
619 The topic branch is deleted to avoid cluttering branch namespace with
620 small topic branches. Information on what issue was fixed or what
621 feature was implemented should be in the commit messages.
627 Git has a builtin merge strategy for what Python core developers call
630 $ git merge -s ours v1 # null-merge v1 into master
636 Git doesn't assume any particular development model regarding
637 branching and merging. Some projects prefer to graduate patches from
638 the oldest branch to the newest, some prefer to cherry-pick commits
639 backwards, some use squashing (combining a number of commits into
640 one). Anything is possible.
642 There are a few examples to start with. `git help workflows
643 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_
644 describes how the very git authors develop git.
646 ProGit book has a few chapters devoted to branch management in
647 different projects: `Git Branching - Branching Workflows
648 <https://git-scm.com/book/en/Git-Branching-Branching-Workflows>`_ and
649 `Distributed Git - Contributing to a Project
650 <https://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project>`_.
652 There is also a well-known article `A successful Git branching model
653 <http://nvie.com/posts/a-successful-git-branching-model/>`_ by Vincent
654 Driessen. It recommends a set of very detailed rules on creating and
655 managing mainline, topic and bugfix branches. To support the model the
656 author implemented `git flow <https://github.com/nvie/gitflow>`_
660 Advanced configuration
661 ======================
666 Git has builtin mechanisms to handle line endings between platforms
667 with different end-of-line styles. To allow git to do CRLF conversion
668 assign ``text`` attribute to files using `.gitattributes
669 <https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
670 For files that have to have specific line endings assign ``eol``
671 attribute. For binary files the attribute is, naturally, ``binary``.
681 To check what attributes git uses for files use ``git check-attr``
682 command. For example::
684 $ git check-attr -a -- \*.py
693 Staging area aka index aka cache is a distinguishing feature of git.
694 Staging area is where git collects patches before committing them.
695 Separation between collecting patches and commit phases provides a
696 very useful feature of git: you can review collected patches before
697 commit and even edit them - remove some hunks, add new hunks and
700 To add files to the index use ``git add``. Collecting patches before
701 committing means you need to do that for every change, not only to add
702 new (untracked) files. To simplify committing in case you just want to
703 commit everything without reviewing run ``git commit --all`` (or just
704 ``-a``) - the command adds every changed tracked file to the index and
705 then commit. To commit a file or files regardless of patches collected
706 in the index run ``git commit [--only|-o] -- $FILE...``.
708 To add hunks of patches to the index use ``git add --patch`` (or just
709 ``-p``). To remove collected files from the index use ``git reset HEAD
710 -- $FILE...`` To add/inspect/remove collected hunks use ``git add
711 --interactive`` (``-i``).
713 To see the diff between the index and the last commit (i.e., collected
714 patches) use ``git diff --cached``. To see the diff between the
715 working tree and the index (i.e., uncollected patches) use just ``git
716 diff``. To see the diff between the working tree and the last commit
717 (i.e., both collected and uncollected patches) run ``git diff HEAD``.
720 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
721 `IndexCommandQuickref
722 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
729 Rerere is a mechanism that helps to resolve repeated merge conflicts.
730 The most frequent source of recurring merge conflicts are topic
731 branches that are merged into mainline and then the merge commits are
732 removed; that's often performed to test the topic branches and train
733 rerere; merge commits are removed to have clean linear history and
734 finish the topic branch with only one last merge commit.
736 Rerere works by remembering the states of tree before and after a
737 successful commit. That way rerere can automatically resolve conflicts
738 if they appear in the same files.
740 Rerere can be used manually with ``git rerere`` command but most often
741 it's used automatically. Enable rerere with these commands in a
744 $ git config rerere.enabled true
745 $ git config rerere.autoupdate true
747 You don't need to turn rerere on globally - you don't want rerere in
748 bare repositories or single-branche repositories; you only need rerere
749 in repos where you often perform merges and resolve merge conflicts.
751 See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
758 Git object database and other files/directories under ``.git`` require
759 periodic maintenance and cleanup. For example, commit editing left
760 unreferenced objects (dangling objects, in git terminology) and these
761 objects should be pruned to avoid collecting cruft in the DB. The
762 command ``git gc`` is used for maintenance. Git automatically runs
763 ``git gc --auto`` as a part of some commands to do quick maintenance.
764 Users are recommended to run ``git gc --aggressive`` from time to
765 time; ``git help gc`` recommends to run it every few hundred
766 changesets; for more intensive projects it should be something like
767 once a week and less frequently (biweekly or monthly) for lesser
770 ``git gc --aggressive`` not only removes dangling objects, it also
771 repacks object database into indexed and better optimized pack(s); it
772 also packs symbolic references (branches and tags). Another way to do
773 it is to run ``git repack``.
775 There is a well-known `message
776 <https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html>`_ from Linus
777 Torvalds regarding "stupidity" of ``git gc --aggressive``. The message
778 can safely be ignored now. It is old and outdated, ``git gc
779 --aggressive`` became much better since that time.
781 For those who still prefer ``git repack`` over ``git gc --aggressive``
782 the recommended parameters are ``git repack -a -d -f --depth=20
783 --window=250``. See `this detailed experiment
784 <http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html>`_
785 for explanation of the effects of these parameters.
787 From time to time run ``git fsck [--strict]`` to verify integrity of
788 the database. ``git fsck`` may produce a list of dangling objects;
789 that's not an error, just a reminder to perform regular maintenance.
795 Command-line options and arguments
796 ----------------------------------
799 <https://www.kernel.org/pub/software/scm/git/docs/gitcli.html>`_
800 recommends not to combine short options/flags. Most of the times
801 combining works: ``git commit -av`` works perfectly, but there are
802 situations when it doesn't. E.g., ``git log -p -5`` cannot be combined
805 Some options have arguments, some even have default arguments. In that
806 case the argument for such option must be spelled in a sticky way:
807 ``-Oarg``, never ``-O arg`` because for an option that has a default
808 argument the latter means "use default value for option ``-O`` and
809 pass ``arg`` further to the option parser". For example, ``git grep``
810 has an option ``-O`` that passes a list of names of the found files to
811 a program; default program for ``-O`` is a pager (usually ``less``),
812 but you can use your editor::
814 $ git grep -Ovim # but not -O vim
816 BTW, if git is instructed to use ``less`` as the pager (i.e., if pager
817 is not configured in git at all it uses ``less`` by default, or if it
818 gets ``less`` from GIT_PAGER or PAGER environment variables, or if it
819 was configured with ``git config --global core.pager less``, or
820 ``less`` is used in the command ``git grep -Oless``) ``git grep``
821 passes ``+/$pattern`` option to ``less`` which is quite convenient.
822 Unfortunately, ``git grep`` doesn't pass the pattern if the pager is
823 not exactly ``less``, even if it's ``less`` with parameters (something
824 like ``git config --global core.pager less -FRSXgimq``); fortunately,
825 ``git grep -Oless`` always passes the pattern.
831 It's a bit hard to type ``git rebase --interactive --preserve-merges
832 HEAD~5`` manually even for those who are happy to use command-line,
833 and this is where shell completion is of great help. Bash/zsh come
834 with programmable completion, often automatically installed and
835 enabled, so if you have bash/zsh and git installed, chances are you
836 are already done - just go and use it at the command-line.
838 If you don't have necessary bits installed, install and enable
839 bash_completion package. If you want to upgrade your git completion to
840 the latest and greatest download necessary file from `git contrib
841 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion>`_.
843 Git-for-windows comes with git-bash for which bash completion is
844 installed and enabled.
850 For command-line lovers shell prompt can carry a lot of useful
851 information. To include git information in the prompt use
853 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion/git-prompt.sh>`_.
854 Read the detailed instructions in the file.
856 Search the Net for "git prompt" to find other prompt variants.
862 The simplest way to publish a repository or a group of repositories is
863 ``git daemon``. The daemon provides anonymous access, by default it is
864 read-only. The repositories are accessible by git protocol (git://
865 URLs). Write access can be enabled but the protocol lacks any
866 authentication means, so it should be enabled only within a trusted
867 LAN. See ``git help daemon`` for details.
869 Git over ssh provides authentication and repo-level authorisation as
870 repositories can be made user- or group-writeable (see parameter
871 ``core.sharedRepository`` in ``git help config``). If that's too
872 permissive or too restrictive for some project's needs there is a
873 wrapper `gitolite <http://gitolite.com/gitolite/index.html>`_ that can
874 be configured to allow access with great granularity; gitolite is
875 written in Perl and has a lot of documentation.
877 Web interface to browse repositories can be created using `gitweb
878 <https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ or `cgit
879 <http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
880 Perl and C). In addition to web interface both provide read-only dumb
881 http access for git (http(s):// URLs). `Klaus
882 <https://pypi.python.org/pypi/klaus>`_ is a small and simple WSGI web
883 server that implements both web interface and git smart HTTP
884 transport; supports Python 2 and Python 3, performs syntax
887 There are also more advanced web-based development environments that
888 include ability to manage users, groups and projects; private,
889 group-accessible and public repositories; they often include issue
890 trackers, wiki pages, pull requests and other tools for development
891 and communication. Among these environments are `Kallithea
892 <https://kallithea-scm.org/>`_ and `pagure <https://pagure.io/>`_,
893 both are written in Python; pagure was written by Fedora developers
894 and is being used to develop some Fedora projects. `GitPrep
895 <http://gitprep.yukikimoto.com/>`_ is yet another Github clone,
896 written in Perl. `Gogs <https://gogs.io/>`_ is written in Go.
897 `GitBucket <https://takezoe.github.io/gitbucket/about/>`_ is written
900 And last but not least, `Gitlab <https://about.gitlab.com/>`_. It's
901 perhaps the most advanced web-based development environment for git.
902 Written in Ruby, community edition is free and open source (MIT
906 From Mercurial to git
907 =====================
909 There are many tools to convert Mercurial repositories to git. The
910 most famous are, probably, `hg-git <https://hg-git.github.io/>`_ and
911 `fast-export <http://repo.or.cz/w/fast-export.git>`_ (many years ago
912 it was known under the name ``hg2git``).
914 But a better tool, perhaps the best, is `git-remote-hg
915 <https://github.com/felipec/git-remote-hg>`_. It provides transparent
916 bidirectional (pull and push) access to Mercurial repositories from
917 git. Its author wrote a `comparison of alternatives
918 <https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives>`_
919 that seems to be mostly objective.
921 To use git-remote-hg, install or clone it, add to your PATH (or copy
922 script ``git-remote-hg`` to a directory that's already in PATH) and
923 prepend ``hg::`` to Mercurial URLs. For example::
925 $ git clone https://github.com/felipec/git-remote-hg.git
926 $ PATH=$PATH:"`pwd`"/git-remote-hg
927 $ git clone hg::https://hg.python.org/peps/ PEPs
929 To work with the repository just use regular git commands including
930 ``git fetch/pull/push``.
932 To start converting your Mercurial habits to git see the page
933 `Mercurial for Git users
934 <https://mercurial.selenic.com/wiki/GitConcepts>`_ at Mercurial wiki.
935 At the second half of the page there is a table that lists
936 corresponding Mercurial and git commands. Should work perfectly in
939 Python Developer's Guide also has a chapter `Mercurial for git
940 developers <https://docs.python.org/devguide/gitdevs.html>`_ that
941 documents a few differences between git and hg.
947 This document has been placed in the public domain.
954 indent-tabs-mode: nil
955 sentence-end-double-space: t
959 vim: set fenc=us-ascii tw=70 :