2 Title: Collecting information about git
5 Author: Oleg Broytman <phd@phdru.name>
8 Content-Type: text/x-rst
15 This Informational PEP collects information about git. There is, of
16 course, a lot of documentation for git, so the PEP concentrates on
17 more complex (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/everyday.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>`_.
69 Git has builtin help: run ``git help $TOPIC``. For example, run
70 ``git help git`` or ``git help help``.
76 Download and installation
77 -------------------------
79 Unix users: `download and install using your package manager
80 <https://git-scm.com/download/linux>`_.
82 Microsoft Windows: download `git-for-windows
83 <https://github.com/git-for-windows/git/releases>`_ or `msysGit
84 <https://github.com/msysgit/msysgit/releases>`_.
86 MacOS X: use git installed with `XCode
87 <https://developer.apple.com/xcode/downloads/>`_ or download from
88 `MacPorts <https://www.macports.org/ports.php?by=name&substr=git>`_ or
90 <http://sourceforge.net/projects/git-osx-installer/files/>`_ or
91 install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
93 `git-cola <https://git-cola.github.io/index.html>`_ is a Git GUI
94 written in Python and GPL licensed. Linux, Windows, MacOS X.
96 `TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
97 to Git based on TortoiseSVN; open source.
100 Initial configuration
101 ---------------------
103 This simple code is often appears in documentation, but it is
104 important so let repeat it here. Git stores author and committer
105 names/emails in every commit, so configure your real name and
108 $ git config --global user.name "User Name"
109 $ git config --global user.email user.name@example.org
115 Examples of git commands in this PEP use the following approach. It is
116 supposed that you, the user, works with a local repository named
117 ``python`` that has an upstream remote repo named ``origin``. Your
118 local repo has two branches ``v1`` and ``master``. For most examples
119 the currently checked out branch is ``master``. That is, it's assumed
120 you have done something like that::
122 $ git clone https://git.python.org/python.git
124 $ git branch v1 origin/v1
126 The first command clones remote repository into local directory
127 `python``, creates a new local branch master, sets
128 remotes/origin/master as its upstream remote-tracking branch and
129 checks it out into the working directory.
131 The last command creates a new local branch v1 and sets
132 remotes/origin/v1 as its upstream remote-tracking branch.
134 The same result can be achieved with commands::
136 $ git clone -b v1 https://git.python.org/python.git
138 $ git checkout --track origin/master
140 The last command creates a new local branch master, sets
141 remotes/origin/master as its upstream remote-tracking branch and
142 checks it out into the working directory.
145 Branches and branches
146 =====================
148 Git terminology can be a bit misleading. Take, for example, the term
149 "branch". In git it has two meanings. A branch is a directed line of
150 commits (possibly with merges). And a branch is a label or a pointer
151 assigned to a line of commits. It is important to distinguish when you
152 talk about commits and when about their labels. Lines of commits are
153 by itself unnamed and are usually only lengthening and merging.
154 Labels, on the other hand, can be created, moved, renamed and deleted
158 Remote repositories and remote branches
159 =======================================
161 Remote-tracking branches are branches (pointers to commits) in your
162 local repository. They are there for git (and for you) to remember
163 what branches and commits have been pulled from and pushed to what
164 remote repos (you can pull from and push to many remotes).
165 Remote-tracking branches live under ``remotes/$REMOTE`` namespaces,
166 e.g. ``remotes/origin/master``.
168 To see the status of remote-tracking branches run::
172 To see local and remote-tracking branches (and tags) pointing to
177 You never do your own development on remote-tracking branches. You
178 create a local branch that has a remote branch as upstream and do
179 development on that local branch. On push git pushes commits to the
180 remote repo and updates remote-tracking branches, on pull git fetches
181 commits from the remote repo, updates remote-tracking branches and
182 fast-forwards, merges or rebases local branches.
184 When you do an initial clone like this::
186 $ git clone -b v1 https://git.python.org/python.git
188 git clones remote repository ``https://git.python.org/python.git`` to
189 directory ``python``, creates a remote named ``origin``, creates
190 remote-tracking branches, creates a local branch ``v1``, configure it
191 to track upstream remotes/origin/v1 branch and checks out ``v1`` into
192 the working directory.
195 Updating local and remote-tracking branches
196 -------------------------------------------
198 There is a major difference between
202 $ git fetch $REMOTE $BRANCH
208 $ git fetch $REMOTE $BRANCH:$BRANCH
210 The first command fetches commits from the named $BRANCH in the
211 $REMOTE repository that are not in your repository, updates
212 remote-tracking branch and leaves the id (the hash) of the head commit
213 in file .git/FETCH_HEAD.
215 The second command fetches commits from the named $BRANCH in the
216 $REMOTE repository that are not in your repository and updates both
217 the local branch $BRANCH and its upstream remote-tracking branch. But
218 it refuses to update branches in case of non-fast-forward. And it
219 refuses to update the current branch (currently checked out branch,
220 where HEAD is pointing to).
222 The first command is used internally by ``git pull``.
226 $ git pull $REMOTE $BRANCH
232 $ git fetch $REMOTE $BRANCH
233 $ git merge FETCH_HEAD
235 Certainly, $BRANCH in that case should be your current branch. If you
236 want to merge a different branch into your current branch first update
237 that non-current branch and then merge::
239 $ git fetch origin v1:v1 # Update v1
240 $ git pull --rebase origin master # Update the current branch master
241 # using rebase instead of merge
244 If you have not yet pushed commits on ``v1``, though, the scenario has
245 to become a bit more complex. Git refuses to update
246 non-fast-forwardable branch, and you don't want to do force-pull
247 because that would remove your non-pushed commits and you would need
248 to recover. So you want to rebase ``v1`` but you cannot rebase
249 non-current branch. Hence, checkout ``v1`` and rebase it before
253 $ git pull --rebase origin v1
254 $ git checkout master
255 $ git pull --rebase origin master
258 It is possible to configure git to make it fetch/pull a few branches
259 or all branches at once, so you can simply run
271 Default remote repository for fetching/pulling is ``origin``. Default
272 set of references to fetch is calculated using matching algorithm: git
273 fetches all branches having the same name on both ends.
278 Pushing is a bit simpler. There is only one command ``push``. When you
283 $ git push origin v1 master
285 git pushes local v1 to remote v1 and local master to remote master.
288 $ git push origin v1:v1 master:master
290 Git pushes commits to the remote repo and updates remote-tracking
291 branches. Git refuses to push commits that aren't fast-forwardable.
292 You can force-push anyway, but please remember - you can force-push to
293 your own repositories but don't force-push to public or shared repos.
294 If you find git refuses to push commits that aren't fast-forwardable,
295 better fetch and merge commits from the remote repo (or rebase your
296 commits on top of the fetched commits), then push. Only force-push if
297 you know what you do and why you do it. See the section `Commit
298 editing and caveats`_ below.
300 It is possible to configure git to make it push a few branches or all
301 branches at once, so you can simply run
313 Default remote repository for pushing is ``origin``. Default set of
314 references to push in git before 2.0 is calculated using matching
315 algorithm: git pushes all branches having the same name on both ends.
316 Default set of references to push in git 2.0+ is calculated using
317 simple algorithm: git pushes the current branch back to its
320 To configure git before 2.0 to the new behaviour run::
322 $ git config push.default simple
324 To configure git 2.0+ to the old behaviour run::
326 $ git config push.default matching
328 Git doesn't allow to push a branch if it's the current branch in the
329 remote non-bare repository: git refuses to update remote working
330 directory. You really should push only to bare repositories. For
331 non-bare repositories git prefers pull-based workflow.
333 When you want to deploy code on a remote host and can only use push
334 (because your workstation is behind a firewall and you cannot pull
335 from it) you do that in two steps using two repositories: you push
336 from the workstation to a bare repo on the remote host, ssh to the
337 remote host and pull from the bare repo to a non-bare deployment repo.
339 That changed in git 2.3, but see `the blog post
340 <https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
341 for caveats; in 2.4 the push-to-deploy feature was `further improved
342 <https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
347 Git automatically fetches tags that point to commits being fetched
348 during fetch/pull. To fetch all tags (and commits they point to) run
349 ``git fetch --tags origin``. To fetch some specific tags fetch them
352 $ git fetch origin tag $TAG1 tag $TAG2...
356 $ git fetch origin tag 1.4.2
357 $ git fetch origin v1:v1 tag 2.1.7
359 Git doesn't automatically pushes tags. That allows you to have private
360 tags. To push tags list them explicitly::
362 $ git push origin tag 1.4.2
363 $ git push origin v1 master tag 2.1.7
365 Or push all tags at once::
367 $ git push --tags origin
369 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
370 after they have been published.
376 When cloning/fetching/pulling/pushing git copies only database objects
377 (commits, trees, files and tags) and symbolic references (branches and
378 lightweight tags). Everything else is private to the repository and
379 never cloned, updated or pushed. It's your config, your hooks, your
380 private exclude file.
382 If you want to distribute hooks, copy them to the working tree, add,
383 commit, push and instruct the team to update and install the hooks
387 Commit editing and caveats
388 ==========================
390 A warning not to edit published (pushed) commits also appears in
391 documentation but it's repeated here anyway as it's very important.
393 It is possible to recover from a forced push but it's PITA for the
394 entire team. Please avoid it.
396 To see what commits have not been published yet compare the head of the
397 branch with its upstream remote-tracking branch::
399 $ git log origin/master.. # from origin/master to HEAD (of master)
400 $ git log origin/v1..v1 # from origin/v1 to the head of v1
402 For every branch that has an upstream remote-tracking branch git
403 maintains an alias @{upstream} (short version @{u}), so the commands
404 above can be given as::
409 To see the status of all branches::
413 To compare the status of local branches with a remote repo::
415 $ git remote show origin
417 Read `how to recover from upstream rebase
418 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
419 It is in ``git help rebase``.
421 On the other hand don't be too afraid about commit editing. You can
422 safely edit, reorder, remove, combine and split commits that haven't
423 been pushed yet. You can even push commits to your own (backup) repo,
424 edit them later and force-push edited commits to replace what have
425 already been pushed. Not a problem until commits are in a public
426 or shared repository.
432 Whatever you do, don't panic. Almost anything in git can be undone.
435 git checkout: restore file's content
436 ------------------------------------
438 ``git checkout``, for example, can be used to restore the content of
439 file(s) to that one of a commit. Like this::
441 git checkout HEAD~ README
443 The commands restores the contents of README file to the last but one
444 commit in the current branch. By default the commit ID is simply HEAD;
445 i.e. ``git checkout README`` restores README to the latest commit.
447 (Do not use ``git checkout`` to view a content of a file in a commit,
448 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
451 git reset: remove (non-pushed) commits
452 --------------------------------------
454 ``git reset`` moves the head of the current branch. The head can be
455 moved to point to any commit but it's often used to remove a commit or
456 a few (preferably, non-pushed ones) from the top of the branch - that
457 is, to move the branch backward in order to undo a few (non-pushed)
460 ``git reset`` has three modes of operation - soft, hard and mixed.
461 Default is mixed. ProGit `explains
462 <https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
463 difference very clearly. Bare repositories don't have indices or
464 working trees so in a bare repo only soft reset is possible.
470 Mixed mode reset with a path or paths can be used to unstage changes -
471 that is, to remove from index changes added with ``git add`` for
472 committing. See `The Book
473 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
474 about unstaging and other undo tricks.
477 git reflog: reference log
478 -------------------------
480 Removing commits with ``git reset`` or moving the head of a branch
481 sounds dangerous and it is. But there is a way to undo: another
482 reset back to the original commit. Git doesn't remove commits
483 immediately; unreferenced commits (in git terminology they are called
484 "dangling commits") stay in the database for some time (default is two
485 weeks) so you can reset back to it or create a new branch pointing to
488 For every move of a branch's head - with ``git commit``, ``git
489 checkout``, ``git fetch``, ``git pull``, ``git rebase``, ``git reset``
490 and so on - git stores a reference log (reflog for short). For every
491 move git stores where the head was. Command ``git reflog`` can be used
492 to view (and manipulate) the log.
494 In addition to the moves of the head of every branch git stores the
495 moves of the HEAD - a symbolic reference that (usually) names the
496 current branch. HEAD is changed with ``git checkout $BRANCH``.
498 By default ``git reflog`` shows the moves of the HEAD, i.e. the
499 command is equivalent to ``git reflog HEAD``. To show the moves of the
500 head of a branch use the command ``git reflog $BRANCH``.
502 So to undo a ``git reset`` lookup the original commit in ``git
503 reflog``, verify it with ``git show`` or ``git log`` and run ``git
504 reset $COMMIT_ID``. Git stores the move of the branch's head in
505 reflog, so you can undo that undo later again.
507 In a more complex situation you'd want to move some commits along with
508 resetting the head of the branch. Cherry-pick them to the new branch.
509 For example, if you want to reset the branch ``master`` back to the
510 original commit but preserve two commits created in the current branch
513 $ git branch save-master # create a new branch saving master
514 $ git reflog # find the original place of master
515 $ git reset $COMMIT_ID
516 $ git cherry-pick save-master~ save-master
517 $ git branch -D save-master # remove temporary branch
520 git revert: revert a commit
521 ---------------------------
523 ``git revert`` reverts a commit or commits, that is, it creates a new
524 commit or commits that revert(s) the effects of the given commits.
525 It's the only way to undo published commits (``git commit --amend``,
526 ``git rebase`` and ``git reset`` change the branch in
527 non-fast-forwardable ways so they should only be used for non-pushed
530 There is a problem with reverting a merge commit. ``git revert`` can
531 undo the code created by the merge commit but it cannot undo the fact
532 of merge. See the discussion `How to revert a faulty merge
533 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
536 One thing that cannot be undone
537 -------------------------------
539 Whatever you undo, there is one thing that cannot be undone -
540 overwritten uncommitted changes. Uncommitted changes don't belong to
541 git so git cannot help preserving them.
543 Most of the time git warns you when you're going to execute a command
544 that overwrites uncommitted changes. Git doesn't allow you to switch
545 branches with ``git checkout``. It stops you when you're going to
546 rebase with non-clean working tree. It refuses to pull new commits
547 over non-committed files.
549 But there are commands that do exactly that - overwrite files in the
550 working tree. Commands like ``git checkout $PATHs`` or ``git reset
551 --hard`` silently overwrite files including your uncommitted changes.
553 With that in mind you can understand the stance "commit early, commit
554 often". Commit as often as possible. Commit on every save in your
555 editor or IDE. You can edit your commits before pushing - edit commit
556 messages, change commits, reorder, combine, split, remove. But save
557 your changes in git database, either commit changes or at least stash
558 them with ``git stash``.
564 Internet is full of heated discussions on the topic: "merge or
565 rebase?" Most of them are meaningless. When a DVCS is being used in a
566 big team with a big and complex project with many branches there is
567 simply no way to avoid merges. So the question's diminished to
568 "whether to use rebase, and if yes - when to use rebase?" Considering
569 that it is very much recommended not to rebase published commits the
570 question's diminished even further: "whether to use rebase on
573 That small question is for the team to decide. The author of the PEP
574 recommends to use rebase when pulling, i.e. always do ``git pull
575 --rebase`` or even configure automatic setup of rebase for every new
578 $ git config branch.autosetuprebase always
580 and configure rebase for existing branches::
582 $ git config branch.$NAME.rebase true
586 $ git config branch.v1.rebase true
587 $ git config branch.master.rebase true
589 After that ``git pull origin master`` becomes equivalent to ``git pull
590 --rebase origin master``.
592 It is recommended to create new commits in a separate feature or topic
593 branch while using rebase to update the mainline branch. When the
594 topic branch is ready merge it into mainline. To avoid a tedious task
595 of resolving large number of conflicts at once you can merge the topic
596 branch to the mainline from time to time and switch back to the topic
597 branch to continue working on it. The entire workflow would be
600 $ git checkout -b issue-42 # create a new issue branch and switch to it
601 ...edit/test/commit...
602 $ git checkout master
603 $ git pull --rebase origin master # update master from the upstream
605 $ git branch -d issue-42 # delete the topic branch
606 $ git push origin master
608 When the topic branch is deleted only the label is removed, commits
609 are stayed in the database, they are now merged into master::
611 o--o--o--o--o--M--< master - the mainline branch
613 --*--*--* - the topic branch, now unnamed
615 The topic branch is deleted to avoid cluttering branch namespace with
616 small topic branches. Information on what issue was fixed or what
617 feature was implemented should be in the commit messages.
623 Git has a builtin merge strategy for what Python core developers call
626 $ git merge -s ours v1 # null-merge v1 into master
629 Advanced configuration
630 ======================
635 Git has builtin mechanisms to handle line endings between platforms
636 with different end-of-line styles. To allow git to do CRLF conversion
637 assign ``text`` attribute to files using `.gitattributes
638 <https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
639 For files that have to have specific line endings assign ``eol``
640 attribute. For binary files the attribute is, naturally, ``binary``.
650 To check what attributes git uses for files use ``git check-attr``
651 command. For example::
653 $ git check-attr -a -- \*.py
662 Staging area aka index aka cache is a distinguishing feature of git.
663 Staging area is where git collects patches before committing them.
664 Separation between collecting patches and commit phases provides a
665 very useful feature of git: you can review collected patches before
666 commit and even edit them - remove some hunks, add new hunks and
669 To add files to the index use ``git add``. Collecting patches before
670 committing means you need to do that for every change, not only to add
671 new (untracked) files. To simplify committing in case you just want to
672 commit everything without reviewing run ``git commit --all`` (or just
673 ``-a``) - the command adds every changed tracked file to the index and
674 then commit. To commit a file or files regardless of patches collected
675 in the index run ``git commit [--only|-o] -- $FILE...``.
677 To add hunks of patches to the index use ``git add --patch`` (or just
678 ``-p``). To remove collected files from the index use ``git reset HEAD
679 -- $FILE...`` To add/inspect/remove collected hunks use ``git add
680 --interactive`` (``-i``).
682 To see the diff between the index and the last commit (i.e., collected
683 patches) use ``git diff --cached``. To see the diff between the
684 working tree and the index (i.e., uncollected patches) use just ``git
685 diff``. To see the diff between the working tree and the last commit
686 (i.e., both collected and uncollected patches) run ``git diff HEAD``.
689 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
690 `IndexCommandQuickref
691 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
698 Rerere is a mechanism that helps to resolve repeated merge conflicts.
699 The most frequent source of recurring merge conflicts are topic
700 branches that are merged into mainline and then the merge commits are
701 removed; that's often performed to test the topic branches and train
702 rerere; merge commits are removed to have clean linear history and
703 finish the topic branch with only one last merge commit.
705 Rerere works by remembering the states of tree before and after a
706 successful commit. That way rerere can automatically resolve conflicts
707 if they appear in the same files.
709 Rerere can be used manually with ``git rerere`` command but most often
710 it's used automatically. Enable rerere with these commands in a
713 $ git config rerere.enabled true
714 $ git config rerere.autoupdate true
716 You don't need to turn rerere on globally - you don't want rerere in
717 bare repositories or single-branche repositories; you only need rerere
718 in repos where you often perform merges and resolve merge conflicts.
720 See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
727 Git object database and other files/directories under ``.git`` require
728 periodic maintenance and cleanup. For example, commit editing left
729 unreferenced objects (dangling objects, in git terminology) and these
730 objects should be pruned to avoid collecting cruft in the DB. The
731 command ``git gc`` is used for maintenance. Git automatically runs
732 ``git gc --auto`` as a part of some commands to do quick maintenance.
733 Users are recommended to run ``git gc --aggressive`` from time to
734 time; ``git help gc`` recommends to run it every few hundred
735 changesets; for more intensive projects it should be something like
736 once a week and less frequently (biweekly or monthly) for lesser
739 ``git gc --aggressive`` not only removes dangling objects, it also
740 repacks object database into indexed and better optimized pack(s); it
741 also packs symbolic references (branches and tags). Another way to do
742 it is to run ``git repack``.
744 There is a well-known `message
745 <https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html>`_ from Linus
746 Torvalds regarding "stupidity" of ``git gc --aggressive``. The message
747 can safely be ignored now. It is old and outdated, ``git gc
748 --aggressive`` became much better since that time.
750 For those who still prefer ``git repack`` over ``git gc --aggressive``
751 the recommended parameters are ``git repack -a -d -f --depth=20
752 --window=250``. See `this detailed experiment
753 <http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html>`_
754 for explanation of the effects of these parameters.
756 From time to time run ``git fsck [--strict]`` to verify integrity of
757 the database. ``git fsck`` may produce a list of dangling objects;
758 that's not an error, just a reminder to perform regular maintenance.
764 Command-line options and arguments
765 ----------------------------------
768 <https://www.kernel.org/pub/software/scm/git/docs/gitcli.html>`_
769 recommends not to combine short options/flags. Most of the times
770 combining works: ``git commit -av`` works perfectly, but there are
771 situations when it doesn't. E.g., ``git log -p -5`` cannot be combined
774 Some options have arguments, some even have default arguments. In that
775 case the argument for such option must be spelled in a sticky way:
776 ``-Oarg``, never ``-O arg`` because for an option that has a default
777 argument the latter means "use default value for option ``-O`` and
778 pass ``arg`` further to the option parser". For example, ``git grep``
779 has an option ``-O`` that passes a list of names of the found files to
780 a program; default program for ``-O`` is a pager (usually ``less``),
781 but you can use your editor::
783 $ git grep -Ovim # but not -O vim
785 BTW, there is a difference between running ``git grep -O`` and ``git
786 grep -Oless`` - in the latter case ``git grep`` passes ``+/pattern``
793 It's a bit hard to type ``git rebase --interactive --preserve-merges
794 HEAD~5`` manually even for those who are happy to use command-line,
795 and this is where shell completion is of great help. Bash/zsh come
796 with programmable completion, often automatically installed and
797 enabled, so if you have bash/zsh and git installed, chances are you
798 are already done - just go and use it at the command-line.
800 If you don't have necessary bits installed, install and enable
801 bash_completion package. If you want to upgrade your git completion to
802 the latest and greatest download necessary file from `git contrib
803 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion>`_.
805 Git-for-windows comes with git-bash for which bash completion is
806 installed and enabled.
812 For command-line lovers shell prompt can carry a lot of useful
813 information. To include git information in the prompt use
815 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion/git-prompt.sh>`_.
816 Read the detailed instructions in the file.
818 Search the Net for "git prompt" to find other prompt variants.
824 The simplest way to publish a repository or a group of repositories is
825 ``git daemon``. The daemon provides anonymous access, by default it is
826 read-only. The repositories are accessible by git protocol (git://
827 URLs). Write access can be enabled but the protocol lacks any
828 authentication means, so it should be enabled only within a trusted
829 LAN. See ``git help daemon`` for details.
831 Git over ssh provides authentication and repo-level authorisation as
832 repositories can be made user- or group-writeable (see parameter
833 ``core.sharedRepository`` in ``git help config``). If that's too
834 permissive or too restrictive for some project's needs there is a
835 wrapper `gitolite <http://gitolite.com/gitolite/index.html>`_ that can
836 be configured to allow access with great granularity; gitolite has a
837 lot of documentation.
839 Web interface to browse repositories can be created using `gitweb
840 <https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ and `cgit
841 <http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
842 Perl and C). In addition to web interface both provide read-only dumb
843 http access for git (http(s):// URLs).
845 There are also more advanced web-based development environments that
846 include ability to manage users, groups and projects; private, group
847 and public repositories; they often include issue trackers, wiki
848 pages, pull requests and other tools for development and
849 communication. Among these environments are `Kallithea
850 <https://kallithea-scm.org/>`_ and `pagure <https://pagure.io/>`_,
851 both are written in Python; pagure was written by Fedora developers
852 and is being used to develop some Fedora projects. `Gogs
853 <http://gogs.io/>`_ is written in Go; there is a fork `Gitea
854 <http://gitea.io/>`_.
856 And last but not least `Gitlab <https://about.gitlab.com/>`_. It's
857 perhaps the most advanced web-based development environment for git.
858 Written in Ruby, community edition is free and open source (MIT
862 From Mercurial to git
863 =====================
865 There are many tools to convert Mercurial repositories to git. The
866 most famous are, perhaps, `hg-git <https://hg-git.github.io/>`_ and
867 `fast-export <http://repo.or.cz/w/fast-export.git>`_ (many years ago
868 it was known under the name ``hg2git``).
870 But a better tool, perhaps the best, is `git-remote-hg
871 <https://github.com/felipec/git-remote-hg>`_. It provides transparent
872 bidirectional access (pull and push) to Mercurial repositories from
873 git. The author wrote a `comparison of alternatives
874 <https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives>`_
875 that seems to be mostly unbiased.
877 To use git-remote-hg, install or clone it, add to your PATH (or copy
878 script ``git-remote-hg`` to a directory that's already in PATH) and
879 prepend ``hg::`` to Mercurial URLs. For example::
881 $ git clone https://github.com/felipec/git-remote-hg.git
882 $ PATH=$PATH:"`pwd`"/git-remote-hg
883 $ git clone hg::https://hg.python.org/peps/ PEPs
885 To work with the repository just use regular git commands including
886 ``git fetch/pull/push``.
888 To start converting your Mercurial habits to git see the page
889 `Mercurial for Git users
890 <https://mercurial.selenic.com/wiki/GitConcepts>`_ at Mercurial wiki.
891 At the second half of the page there is a table that lists
892 corresponding Mercurial and git commands. Should work perfectly in
899 This document has been placed in the public domain.
906 indent-tabs-mode: nil
907 sentence-end-double-space: t
911 vim: set fenc=us-ascii tw=70 :