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 There is a major difference between
212 $ git fetch $REMOTE $BRANCH
218 $ git fetch $REMOTE $BRANCH:$BRANCH
220 The first command fetches commits from the named $BRANCH in the
221 $REMOTE repository that are not in your repository, updates
222 remote-tracking branch and leaves the id (the hash) of the head commit
223 in file .git/FETCH_HEAD.
225 The second command fetches commits from the named $BRANCH in the
226 $REMOTE repository that are not in your repository and updates both
227 the local branch $BRANCH and its upstream remote-tracking branch. But
228 it refuses to update branches in case of non-fast-forward. And it
229 refuses to update the current branch (currently checked out branch,
230 where HEAD is pointing to).
232 The first command is used internally by ``git pull``.
236 $ git pull $REMOTE $BRANCH
242 $ git fetch $REMOTE $BRANCH
243 $ git merge FETCH_HEAD
245 Certainly, $BRANCH in that case should be your current branch. If you
246 want to merge a different branch into your current branch first update
247 that non-current branch and then merge::
249 $ git fetch origin v1:v1 # Update v1
250 $ git pull --rebase origin master # Update the current branch master
251 # using rebase instead of merge
254 If you have not yet pushed commits on ``v1``, though, the scenario has
255 to become a bit more complex. Git refuses to update
256 non-fast-forwardable branch, and you don't want to do force-pull
257 because that would remove your non-pushed commits and you would need
258 to recover. So you want to rebase ``v1`` but you cannot rebase
259 non-current branch. Hence, checkout ``v1`` and rebase it before
263 $ git pull --rebase origin v1
264 $ git checkout master
265 $ git pull --rebase origin master
268 It is possible to configure git to make it fetch/pull a few branches
269 or all branches at once, so you can simply run
281 Default remote repository for fetching/pulling is ``origin``. Default
282 set of references to fetch is calculated using matching algorithm: git
283 fetches all branches having the same name on both ends.
289 Pushing is a bit simpler. There is only one command ``push``. When you
294 $ git push origin v1 master
296 git pushes local v1 to remote v1 and local master to remote master.
299 $ git push origin v1:v1 master:master
301 Git pushes commits to the remote repo and updates remote-tracking
302 branches. Git refuses to push commits that aren't fast-forwardable.
303 You can force-push anyway, but please remember - you can force-push to
304 your own repositories but don't force-push to public or shared repos.
305 If you find git refuses to push commits that aren't fast-forwardable,
306 better fetch and merge commits from the remote repo (or rebase your
307 commits on top of the fetched commits), then push. Only force-push if
308 you know what you do and why you do it. See the section `Commit
309 editing and caveats`_ below.
311 It is possible to configure git to make it push a few branches or all
312 branches at once, so you can simply run
324 Default remote repository for pushing is ``origin``. Default set of
325 references to push in git before 2.0 is calculated using matching
326 algorithm: git pushes all branches having the same name on both ends.
327 Default set of references to push in git 2.0+ is calculated using
328 simple algorithm: git pushes the current branch back to its
331 To configure git before 2.0 to the new behaviour run::
333 $ git config push.default simple
335 To configure git 2.0+ to the old behaviour run::
337 $ git config push.default matching
339 Git doesn't allow to push a branch if it's the current branch in the
340 remote non-bare repository: git refuses to update remote working
341 directory. You really should push only to bare repositories. For
342 non-bare repositories git prefers pull-based workflow.
344 When you want to deploy code on a remote host and can only use push
345 (because your workstation is behind a firewall and you cannot pull
346 from it) you do that in two steps using two repositories: you push
347 from the workstation to a bare repo on the remote host, ssh to the
348 remote host and pull from the bare repo to a non-bare deployment repo.
350 That changed in git 2.3, but see `the blog post
351 <https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
352 for caveats; in 2.4 the push-to-deploy feature was `further improved
353 <https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
355 To update remote-tracking branches without updating local branches run
356 ``git remote update [$REMOTE...]``. For example::
359 $ git remote update origin
365 Git automatically fetches tags that point to commits being fetched
366 during fetch/pull. To fetch all tags (and commits they point to) run
367 ``git fetch --tags origin``. To fetch some specific tags fetch them
370 $ git fetch origin tag $TAG1 tag $TAG2...
374 $ git fetch origin tag 1.4.2
375 $ git fetch origin v1:v1 tag 2.1.7
377 Git doesn't automatically pushes tags. That allows you to have private
378 tags. To push tags list them explicitly::
380 $ git push origin tag 1.4.2
381 $ git push origin v1 master tag 2.1.7
383 Or push all tags at once::
385 $ git push --tags origin
387 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
388 after they have been published.
394 When cloning/fetching/pulling/pushing git copies only database objects
395 (commits, trees, files and tags) and symbolic references (branches and
396 lightweight tags). Everything else is private to the repository and
397 never cloned, updated or pushed. It's your config, your hooks, your
398 private exclude file.
400 If you want to distribute hooks, copy them to the working tree, add,
401 commit, push and instruct the team to update and install the hooks
405 Commit editing and caveats
406 ==========================
408 A warning not to edit published (pushed) commits also appears in
409 documentation but it's repeated here anyway as it's very important.
411 It is possible to recover from a forced push but it's PITA for the
412 entire team. Please avoid it.
414 To see what commits have not been published yet compare the head of the
415 branch with its upstream remote-tracking branch::
417 $ git log origin/master.. # from origin/master to HEAD (of master)
418 $ git log origin/v1..v1 # from origin/v1 to the head of v1
420 For every branch that has an upstream remote-tracking branch git
421 maintains an alias @{upstream} (short version @{u}), so the commands
422 above can be given as::
427 To see the status of all branches::
431 To compare the status of local branches with a remote repo::
433 $ git remote show origin
435 Read `how to recover from upstream rebase
436 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
437 It is in ``git help rebase``.
439 On the other hand don't be too afraid about commit editing. You can
440 safely edit, reorder, remove, combine and split commits that haven't
441 been pushed yet. You can even push commits to your own (backup) repo,
442 edit them later and force-push edited commits to replace what have
443 already been pushed. Not a problem until commits are in a public
444 or shared repository.
450 Whatever you do, don't panic. Almost anything in git can be undone.
453 git checkout: restore file's content
454 ------------------------------------
456 ``git checkout``, for example, can be used to restore the content of
457 file(s) to that one of a commit. Like this::
459 git checkout HEAD~ README
461 The commands restores the contents of README file to the last but one
462 commit in the current branch. By default the commit ID is simply HEAD;
463 i.e. ``git checkout README`` restores README to the latest commit.
465 (Do not use ``git checkout`` to view a content of a file in a commit,
466 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
469 git reset: remove (non-pushed) commits
470 --------------------------------------
472 ``git reset`` moves the head of the current branch. The head can be
473 moved to point to any commit but it's often used to remove a commit or
474 a few (preferably, non-pushed ones) from the top of the branch - that
475 is, to move the branch backward in order to undo a few (non-pushed)
478 ``git reset`` has three modes of operation - soft, hard and mixed.
479 Default is mixed. ProGit `explains
480 <https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
481 difference very clearly. Bare repositories don't have indices or
482 working trees so in a bare repo only soft reset is possible.
488 Mixed mode reset with a path or paths can be used to unstage changes -
489 that is, to remove from index changes added with ``git add`` for
490 committing. See `The Book
491 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
492 about unstaging and other undo tricks.
495 git reflog: reference log
496 -------------------------
498 Removing commits with ``git reset`` or moving the head of a branch
499 sounds dangerous and it is. But there is a way to undo: another
500 reset back to the original commit. Git doesn't remove commits
501 immediately; unreferenced commits (in git terminology they are called
502 "dangling commits") stay in the database for some time (default is two
503 weeks) so you can reset back to it or create a new branch pointing to
506 For every move of a branch's head - with ``git commit``, ``git
507 checkout``, ``git fetch``, ``git pull``, ``git rebase``, ``git reset``
508 and so on - git stores a reference log (reflog for short). For every
509 move git stores where the head was. Command ``git reflog`` can be used
510 to view (and manipulate) the log.
512 In addition to the moves of the head of every branch git stores the
513 moves of the HEAD - a symbolic reference that (usually) names the
514 current branch. HEAD is changed with ``git checkout $BRANCH``.
516 By default ``git reflog`` shows the moves of the HEAD, i.e. the
517 command is equivalent to ``git reflog HEAD``. To show the moves of the
518 head of a branch use the command ``git reflog $BRANCH``.
520 So to undo a ``git reset`` lookup the original commit in ``git
521 reflog``, verify it with ``git show`` or ``git log`` and run ``git
522 reset $COMMIT_ID``. Git stores the move of the branch's head in
523 reflog, so you can undo that undo later again.
525 In a more complex situation you'd want to move some commits along with
526 resetting the head of the branch. Cherry-pick them to the new branch.
527 For example, if you want to reset the branch ``master`` back to the
528 original commit but preserve two commits created in the current branch
531 $ git branch save-master # create a new branch saving master
532 $ git reflog # find the original place of master
533 $ git reset $COMMIT_ID
534 $ git cherry-pick save-master~ save-master
535 $ git branch -D save-master # remove temporary branch
538 git revert: revert a commit
539 ---------------------------
541 ``git revert`` reverts a commit or commits, that is, it creates a new
542 commit or commits that revert(s) the effects of the given commits.
543 It's the only way to undo published commits (``git commit --amend``,
544 ``git rebase`` and ``git reset`` change the branch in
545 non-fast-forwardable ways so they should only be used for non-pushed
548 There is a problem with reverting a merge commit. ``git revert`` can
549 undo the code created by the merge commit but it cannot undo the fact
550 of merge. See the discussion `How to revert a faulty merge
551 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
554 One thing that cannot be undone
555 -------------------------------
557 Whatever you undo, there is one thing that cannot be undone -
558 overwritten uncommitted changes. Uncommitted changes don't belong to
559 git so git cannot help preserving them.
561 Most of the time git warns you when you're going to execute a command
562 that overwrites uncommitted changes. Git doesn't allow you to switch
563 branches with ``git checkout``. It stops you when you're going to
564 rebase with non-clean working tree. It refuses to pull new commits
565 over non-committed files.
567 But there are commands that do exactly that - overwrite files in the
568 working tree. Commands like ``git checkout $PATHs`` or ``git reset
569 --hard`` silently overwrite files including your uncommitted changes.
571 With that in mind you can understand the stance "commit early, commit
572 often". Commit as often as possible. Commit on every save in your
573 editor or IDE. You can edit your commits before pushing - edit commit
574 messages, change commits, reorder, combine, split, remove. But save
575 your changes in git database, either commit changes or at least stash
576 them with ``git stash``.
582 Internet is full of heated discussions on the topic: "merge or
583 rebase?" Most of them are meaningless. When a DVCS is being used in a
584 big team with a big and complex project with many branches there is
585 simply no way to avoid merges. So the question's diminished to
586 "whether to use rebase, and if yes - when to use rebase?" Considering
587 that it is very much recommended not to rebase published commits the
588 question's diminished even further: "whether to use rebase on
591 That small question is for the team to decide. The author of the PEP
592 recommends to use rebase when pulling, i.e. always do ``git pull
593 --rebase`` or even configure automatic setup of rebase for every new
596 $ git config branch.autosetuprebase always
598 and configure rebase for existing branches::
600 $ git config branch.$NAME.rebase true
604 $ git config branch.v1.rebase true
605 $ git config branch.master.rebase true
607 After that ``git pull origin master`` becomes equivalent to ``git pull
608 --rebase origin master``.
610 It is recommended to create new commits in a separate feature or topic
611 branch while using rebase to update the mainline branch. When the
612 topic branch is ready merge it into mainline. To avoid a tedious task
613 of resolving large number of conflicts at once you can merge the topic
614 branch to the mainline from time to time and switch back to the topic
615 branch to continue working on it. The entire workflow would be
618 $ git checkout -b issue-42 # create a new issue branch and switch to it
619 ...edit/test/commit...
620 $ git checkout master
621 $ git pull --rebase origin master # update master from the upstream
623 $ git branch -d issue-42 # delete the topic branch
624 $ git push origin master
626 When the topic branch is deleted only the label is removed, commits
627 are stayed in the database, they are now merged into master::
629 o--o--o--o--o--M--< master - the mainline branch
631 --*--*--* - the topic branch, now unnamed
633 The topic branch is deleted to avoid cluttering branch namespace with
634 small topic branches. Information on what issue was fixed or what
635 feature was implemented should be in the commit messages.
641 Git has a builtin merge strategy for what Python core developers call
644 $ git merge -s ours v1 # null-merge v1 into master
650 Git doesn't assume any particular development model regarding
651 branching and merging. Some projects prefer to graduate patches from
652 the oldest branch to the newest, some prefer to cherry-pick commits
653 backwards, some use squashing (combining a number of commits into
654 one). Anything is possible.
656 There are a few examples to start with. `git help workflows
657 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_
658 describes how the very git authors develop git.
660 ProGit book has a few chapters devoted to branch management in
661 different projects: `Git Branching - Branching Workflows
662 <https://git-scm.com/book/en/Git-Branching-Branching-Workflows>`_ and
663 `Distributed Git - Contributing to a Project
664 <https://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project>`_.
666 There is also a well-known article `A successful Git branching model
667 <http://nvie.com/posts/a-successful-git-branching-model/>`_ by Vincent
668 Driessen. It recommends a set of very detailed rules on creating and
669 managing mainline, topic and bugfix branches. To support the model the
670 author implemented `git flow <https://github.com/nvie/gitflow>`_
674 Advanced configuration
675 ======================
680 Git has builtin mechanisms to handle line endings between platforms
681 with different end-of-line styles. To allow git to do CRLF conversion
682 assign ``text`` attribute to files using `.gitattributes
683 <https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
684 For files that have to have specific line endings assign ``eol``
685 attribute. For binary files the attribute is, naturally, ``binary``.
695 To check what attributes git uses for files use ``git check-attr``
696 command. For example::
698 $ git check-attr -a -- \*.py
707 Staging area aka index aka cache is a distinguishing feature of git.
708 Staging area is where git collects patches before committing them.
709 Separation between collecting patches and commit phases provides a
710 very useful feature of git: you can review collected patches before
711 commit and even edit them - remove some hunks, add new hunks and
714 To add files to the index use ``git add``. Collecting patches before
715 committing means you need to do that for every change, not only to add
716 new (untracked) files. To simplify committing in case you just want to
717 commit everything without reviewing run ``git commit --all`` (or just
718 ``-a``) - the command adds every changed tracked file to the index and
719 then commit. To commit a file or files regardless of patches collected
720 in the index run ``git commit [--only|-o] -- $FILE...``.
722 To add hunks of patches to the index use ``git add --patch`` (or just
723 ``-p``). To remove collected files from the index use ``git reset HEAD
724 -- $FILE...`` To add/inspect/remove collected hunks use ``git add
725 --interactive`` (``-i``).
727 To see the diff between the index and the last commit (i.e., collected
728 patches) use ``git diff --cached``. To see the diff between the
729 working tree and the index (i.e., uncollected patches) use just ``git
730 diff``. To see the diff between the working tree and the last commit
731 (i.e., both collected and uncollected patches) run ``git diff HEAD``.
734 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
735 `IndexCommandQuickref
736 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
743 Rerere is a mechanism that helps to resolve repeated merge conflicts.
744 The most frequent source of recurring merge conflicts are topic
745 branches that are merged into mainline and then the merge commits are
746 removed; that's often performed to test the topic branches and train
747 rerere; merge commits are removed to have clean linear history and
748 finish the topic branch with only one last merge commit.
750 Rerere works by remembering the states of tree before and after a
751 successful commit. That way rerere can automatically resolve conflicts
752 if they appear in the same files.
754 Rerere can be used manually with ``git rerere`` command but most often
755 it's used automatically. Enable rerere with these commands in a
758 $ git config rerere.enabled true
759 $ git config rerere.autoupdate true
761 You don't need to turn rerere on globally - you don't want rerere in
762 bare repositories or single-branche repositories; you only need rerere
763 in repos where you often perform merges and resolve merge conflicts.
765 See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
772 Git object database and other files/directories under ``.git`` require
773 periodic maintenance and cleanup. For example, commit editing left
774 unreferenced objects (dangling objects, in git terminology) and these
775 objects should be pruned to avoid collecting cruft in the DB. The
776 command ``git gc`` is used for maintenance. Git automatically runs
777 ``git gc --auto`` as a part of some commands to do quick maintenance.
778 Users are recommended to run ``git gc --aggressive`` from time to
779 time; ``git help gc`` recommends to run it every few hundred
780 changesets; for more intensive projects it should be something like
781 once a week and less frequently (biweekly or monthly) for lesser
784 ``git gc --aggressive`` not only removes dangling objects, it also
785 repacks object database into indexed and better optimized pack(s); it
786 also packs symbolic references (branches and tags). Another way to do
787 it is to run ``git repack``.
789 There is a well-known `message
790 <https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html>`_ from Linus
791 Torvalds regarding "stupidity" of ``git gc --aggressive``. The message
792 can safely be ignored now. It is old and outdated, ``git gc
793 --aggressive`` became much better since that time.
795 For those who still prefer ``git repack`` over ``git gc --aggressive``
796 the recommended parameters are ``git repack -a -d -f --depth=20
797 --window=250``. See `this detailed experiment
798 <http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html>`_
799 for explanation of the effects of these parameters.
801 From time to time run ``git fsck [--strict]`` to verify integrity of
802 the database. ``git fsck`` may produce a list of dangling objects;
803 that's not an error, just a reminder to perform regular maintenance.
809 Command-line options and arguments
810 ----------------------------------
813 <https://www.kernel.org/pub/software/scm/git/docs/gitcli.html>`_
814 recommends not to combine short options/flags. Most of the times
815 combining works: ``git commit -av`` works perfectly, but there are
816 situations when it doesn't. E.g., ``git log -p -5`` cannot be combined
819 Some options have arguments, some even have default arguments. In that
820 case the argument for such option must be spelled in a sticky way:
821 ``-Oarg``, never ``-O arg`` because for an option that has a default
822 argument the latter means "use default value for option ``-O`` and
823 pass ``arg`` further to the option parser". For example, ``git grep``
824 has an option ``-O`` that passes a list of names of the found files to
825 a program; default program for ``-O`` is a pager (usually ``less``),
826 but you can use your editor::
828 $ git grep -Ovim # but not -O vim
830 BTW, if git is instructed to use ``less`` as the pager (i.e., if pager
831 is not configured in git at all it uses ``less`` by default, or if it
832 gets ``less`` from GIT_PAGER or PAGER environment variables, or if it
833 was configured with ``git config --global core.pager less``, or
834 ``less`` is used in the command ``git grep -Oless``) ``git grep``
835 passes ``+/$pattern`` option to ``less`` which is quite convenient.
836 Unfortunately, ``git grep`` doesn't pass the pattern if the pager is
837 not exactly ``less``, even if it's ``less`` with parameters (something
838 like ``git config --global core.pager less -FRSXgimq``); fortunately,
839 ``git grep -Oless`` always passes the pattern.
845 It's a bit hard to type ``git rebase --interactive --preserve-merges
846 HEAD~5`` manually even for those who are happy to use command-line,
847 and this is where shell completion is of great help. Bash/zsh come
848 with programmable completion, often automatically installed and
849 enabled, so if you have bash/zsh and git installed, chances are you
850 are already done - just go and use it at the command-line.
852 If you don't have necessary bits installed, install and enable
853 bash_completion package. If you want to upgrade your git completion to
854 the latest and greatest download necessary file from `git contrib
855 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion>`_.
857 Git-for-windows comes with git-bash for which bash completion is
858 installed and enabled.
864 For command-line lovers shell prompt can carry a lot of useful
865 information. To include git information in the prompt use
867 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion/git-prompt.sh>`_.
868 Read the detailed instructions in the file.
870 Search the Net for "git prompt" to find other prompt variants.
876 The simplest way to publish a repository or a group of repositories is
877 ``git daemon``. The daemon provides anonymous access, by default it is
878 read-only. The repositories are accessible by git protocol (git://
879 URLs). Write access can be enabled but the protocol lacks any
880 authentication means, so it should be enabled only within a trusted
881 LAN. See ``git help daemon`` for details.
883 Git over ssh provides authentication and repo-level authorisation as
884 repositories can be made user- or group-writeable (see parameter
885 ``core.sharedRepository`` in ``git help config``). If that's too
886 permissive or too restrictive for some project's needs there is a
887 wrapper `gitolite <http://gitolite.com/gitolite/index.html>`_ that can
888 be configured to allow access with great granularity; gitolite is
889 written in Perl and has a lot of documentation.
891 Web interface to browse repositories can be created using `gitweb
892 <https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ or `cgit
893 <http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
894 Perl and C). In addition to web interface both provide read-only dumb
895 http access for git (http(s):// URLs). `Klaus
896 <https://pypi.python.org/pypi/klaus>`_ is a small and simple WSGI web
897 server that implements both web interface and git smart HTTP
898 transport; supports Python 2 and Python 3, performs syntax
901 There are also more advanced web-based development environments that
902 include ability to manage users, groups and projects; private,
903 group-accessible and public repositories; they often include issue
904 trackers, wiki pages, pull requests and other tools for development
905 and communication. Among these environments are `Kallithea
906 <https://kallithea-scm.org/>`_ and `pagure <https://pagure.io/>`_,
907 both are written in Python; pagure was written by Fedora developers
908 and is being used to develop some Fedora projects. `GitPrep
909 <http://gitprep.yukikimoto.com/>`_ is yet another Github clone,
910 written in Perl. `Gogs <https://gogs.io/>`_ is written in Go.
911 `GitBucket <https://takezoe.github.io/gitbucket/about/>`_ is written
914 And last but not least, `Gitlab <https://about.gitlab.com/>`_. It's
915 perhaps the most advanced web-based development environment for git.
916 Written in Ruby, community edition is free and open source (MIT
920 From Mercurial to git
921 =====================
923 There are many tools to convert Mercurial repositories to git. The
924 most famous are, probably, `hg-git <https://hg-git.github.io/>`_ and
925 `fast-export <http://repo.or.cz/w/fast-export.git>`_ (many years ago
926 it was known under the name ``hg2git``).
928 But a better tool, perhaps the best, is `git-remote-hg
929 <https://github.com/felipec/git-remote-hg>`_. It provides transparent
930 bidirectional (pull and push) access to Mercurial repositories from
931 git. Its author wrote a `comparison of alternatives
932 <https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives>`_
933 that seems to be mostly objective.
935 To use git-remote-hg, install or clone it, add to your PATH (or copy
936 script ``git-remote-hg`` to a directory that's already in PATH) and
937 prepend ``hg::`` to Mercurial URLs. For example::
939 $ git clone https://github.com/felipec/git-remote-hg.git
940 $ PATH=$PATH:"`pwd`"/git-remote-hg
941 $ git clone hg::https://hg.python.org/peps/ PEPs
943 To work with the repository just use regular git commands including
944 ``git fetch/pull/push``.
946 To start converting your Mercurial habits to git see the page
947 `Mercurial for Git users
948 <https://mercurial.selenic.com/wiki/GitConcepts>`_ at Mercurial wiki.
949 At the second half of the page there is a table that lists
950 corresponding Mercurial and git commands. Should work perfectly in
953 Python Developer's Guide also has a chapter `Mercurial for git
954 developers <https://docs.python.org/devguide/gitdevs.html>`_ that
955 documents a few differences between git and hg.
961 This document has been placed in the public domain.
968 indent-tabs-mode: nil
969 sentence-end-double-space: t
973 vim: set fenc=us-ascii tw=70 :