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 issues, scenarios and examples.
19 The plan is to extend the PEP in the future collecting information
20 about equivalence of Mercurial and git scenarios to help migrating
21 Python development from Mercurial to git.
23 The author of the PEP doesn't currently plan to write a Process PEP on
24 migration from Mercurial to git.
30 Git is accompanied with a lot of documentation, both online and
34 Documentation for starters
35 --------------------------
38 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html>`_,
40 <https://www.kernel.org/pub/software/scm/git/docs/gittutorial-2.html>`_.
43 <https://www.kernel.org/pub/software/scm/git/docs/user-manual.html>`_.
44 `Everyday GIT With 20 Commands Or So
45 <https://www.kernel.org/pub/software/scm/git/docs/everyday.html>`_.
47 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
50 Advanced documentation
51 ----------------------
54 <http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html>`_,
55 with a number of translations.
57 `Pro Git <https://git-scm.com/book>`_. The Book about git. Buy it at
58 Amazon or download in PDF, mobi, or ePub form. Has translations to
59 many different languages. Download Russian translation from `GArik
60 <https://github.com/GArik/progit/wiki>`_.
62 `Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
68 Git has builtin help: run ``git help $TOPIC``. For example, run
69 ``git help git`` or ``git help help``.
75 Download and installation
76 -------------------------
78 Unix users: `download and install using your package manager
79 <https://git-scm.com/download/linux>`_.
81 Microsoft Windows: download `git-for-windows
82 <https://github.com/git-for-windows/git/releases>`_ or `msysGit
83 <https://github.com/msysgit/msysgit/releases>`_.
85 MacOS X: use git installed with `XCode
86 <https://developer.apple.com/xcode/downloads/>`_ or download from
87 `MacPorts <https://www.macports.org/ports.php?by=name&substr=git>`_ or
89 <http://sourceforge.net/projects/git-osx-installer/files/>`_ or
90 install git with `Homebrew <http://brew.sh/>`_: ``brew install git``.
92 `git-cola <https://git-cola.github.io/index.html>`_ is a Git GUI
93 written in Python and GPL licensed. Linux, Windows, MacOS X.
95 `TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
96 to Git based on TortoiseSVN; open source.
100 ---------------------
102 This simple code is often appears in documentation, but it is
103 important so let repeat it here. Git stores author and committer
104 names/emails in every commit, so configure your real name and
107 $ git config --global user.name "User Name"
108 $ git config --global user.email user.name@example.org
114 Examples of git commands in this PEP use the following approach. It is
115 supposed that you, the user, works with a local repository named
116 ``python`` that has an upstream remote repo named ``origin``. Your
117 local repo has two branches ``v1`` and ``master``. For most examples
118 the currently checked out branch is ``master``. That is, it's assumed
119 you have done something like that::
121 $ git clone https://git.python.org/python.git
123 $ git branch v1 origin/v1
125 The first command clones remote repository into local directory
126 `python``, creates a new local branch master, sets
127 remotes/origin/master as its upstream remote-tracking branch and
128 checks it out into the working directory.
130 The last command creates a new local branch v1 and sets
131 remotes/origin/v1 as its upstream remote-tracking branch.
133 The same result can be achieved with commands::
135 $ git clone -b v1 https://git.python.org/python.git
137 $ git checkout --track origin/master
139 The last command creates a new local branch master, sets
140 remotes/origin/master as its upstream remote-tracking branch and
141 checks it out into the working directory.
144 Branches and branches
145 =====================
147 Git terminology can be a bit misleading. Take, for example, the term
148 "branch". In git it has two meanings. A branch is a directed line of
149 commits (possibly with merges). And a branch is a label or a pointer
150 assigned to a line of commits. It is important to distinguish when you
151 talk about commits and when about their labels. Lines of commits are
152 by itself unnamed and are usually only lengthening and merging.
153 Labels, on the other hand, can be created, moved, renamed and deleted
157 Remote repositories and remote branches
158 =======================================
160 Remote-tracking branches are branches (pointers to commits) in your
161 local repository. They are there for you to remember what branches and
162 commits have been pulled from and pushed to what remote repos (you can
163 pull from and push to many remotes). Remote-tracking branches live
164 under ``remotes/$REMOTE`` namespaces, e.g. ``remotes/origin/master``.
166 To see the status of remote-tracking branches run::
170 To see local and remote-tracking branches (and tags) pointing to
175 You never do your own development on remote-tracking branches. You
176 create a local branch that has a remote branch as upstream and do
177 development on that local branch. On push git pushes commits to the
178 remote repo and updates remote-tracking branches, on pull git fetches
179 commits from the remote repo, updates remote-tracking branches and
180 fast-forwards, merges or rebases local branches.
182 When you do an initial clone like this::
184 $ git clone -b v1 https://git.python.org/python.git
186 git clones remote repository ``https://git.python.org/python.git`` to
187 directory ``python``, creates a remote named ``origin``, creates
188 remote-tracking branches, creates a local branch ``v1``, configure it
189 to track upstream remotes/origin/v1 branch and checks out ``v1`` into
190 the working directory.
193 Updating local and remote-tracking branches
194 -------------------------------------------
196 There is a major difference between
200 $ git fetch $REMOTE $BRANCH
206 $ git fetch $REMOTE $BRANCH:$BRANCH
208 The first command fetches commits from the named $BRANCH in the
209 $REMOTE repository that are not in your repository, updates
210 remote-tracking branch and leaves the id (the hash) of the head commit
211 in file .git/FETCH_HEAD.
213 The second command fetches commits from the named $BRANCH in the
214 $REMOTE repository that are not in your repository and updates both
215 the local branch $BRANCH and its upstream remote-tracking branch. But
216 it refuses to update branches in case of non-fast-forward. And it
217 refuses to update the current branch (currently checked out branch,
218 where HEAD is pointing to).
220 The first command is used internally by ``git pull``.
224 $ git pull $REMOTE $BRANCH
230 $ git fetch $REMOTE $BRANCH
231 $ git merge FETCH_HEAD
233 Certainly, $BRANCH in that case should be your current branch. If you
234 want to merge a different branch into your current branch first update
235 that non-current branch and then merge::
237 $ git fetch origin v1:v1 # Update v1
238 $ git pull --rebase origin master # Update the current branch master
239 # using rebase instead of merge
242 If you have not yet pushed commits on ``v1``, though, the scenario has
243 to become a bit more complex. Git refuses to update
244 non-fast-forwardable branch, and you don't want to do force-pull
245 because that would remove your non-pushed commits and you would need
246 to recover. So you want to rebase ``v1`` but you cannot rebase
247 non-current branch. Hence, checkout ``v1`` and rebase it before
251 $ git pull --rebase origin v1
252 $ git checkout master
253 $ git pull --rebase origin master
256 It is possible to configure git to make it fetch/pull a few branches
257 or all branches at once, so you can simply run
269 Default remote repository for fetching/pulling is origin. Default set
270 of references to fetch is calculated using matching algorithm: git
271 fetches all branches having the same name on both ends.
276 Pushing is a bit simpler. There is only one command ``push``. When you
281 $ git push origin v1 master
283 git pushes local v1 to remote v1 and local master to remote master.
286 $ git push origin v1:v1 master:master
288 Git pushes commits to the remote repo and updates remote-tracking
289 branches. Git refuses to push commits that aren't fast-forwardable.
290 You can force-push anyway, but please remember - you can force-push to
291 your own repositories but don't force-push to public or shared repos.
292 If you find git refuses to push commits that aren't fast-forwardable,
293 better fetch and merge commits from the remote repo (or rebase your
294 commits on top of the fetched commits), then push. Only force-push if
295 you know what you do and why you do it. See the section `Commit
296 editing and caveats`_ below.
298 It is possible to configure git to make it push a few branches or all
299 branches at once, so you can simply run
311 Default remote repository for pushing is origin. Default set
312 of references to push in git before 2.0 is calculated using matching
313 algorithm: git pushes all branches having the same name on both ends.
314 Default set of references to push in git 2.0+ is calculated using
315 simple algorithm: git pushes the current branch back to its
318 To configure git before 2.0 to the new behaviour run::
320 $ git config push.default simple
322 To configure git 2.0+ to the old behaviour run::
324 $ git config push.default matching
326 Git refuses to push a branch if it's the current branch in the remote
327 non-bare repository: git refuses to update remote working directory.
328 You really should push only to bare repositories. For non-bare
329 repositories git prefers pull-based workflow.
331 When you want to deploy code on a remote host and can only use push
332 (because your workstation is behind a firewall and you cannot pull
333 from it) you do that in two steps using two repositories: you push
334 from the workstation to a bare repo on the remote host, ssh to the
335 remote host and pull from the bare repo to a non-bare deployment repo.
337 That changed in git 2.3, but see `the blog post
338 <https://github.com/blog/1957-git-2-3-has-been-released#push-to-deploy>`_
339 for caveats; in 2.4 the push-to-deploy feature was `further improved
340 <https://github.com/blog/1994-git-2-4-atomic-pushes-push-to-deploy-and-more#push-to-deploy-improvements>`_.
345 Git automatically fetches tags that point to commits being fetched
346 during fetch/pull. To fetch all tags (and commits they point to) run
347 ``git fetch --tags origin``. To fetch some specific tags fetch them
350 $ git fetch origin tag $TAG1 tag $TAG2...
354 $ git fetch origin tag 1.4.2
355 $ git fetch origin v1:v1 tag 2.1.7
357 Git doesn't automatically pushes tags. That allows you to have private
358 tags. To push tags list them explicitly::
360 $ git push origin tag 1.4.2
361 $ git push origin v1 master tag 2.1.7
363 Or push all tags at once::
365 $ git push --tags origin
367 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
368 after they have been published.
374 When cloning/fetching/pulling/pushing git copies only database objects
375 (commits, trees, files and tags) and symbolic references (branches and
376 lightweight tags). Everything else is private to the repository and
377 never cloned, updated or pushed. It's your config, your hooks, your
378 private exclude file.
380 If you want to distribute hooks, copy them to the working tree, add,
381 commit, push and instruct the team to update ind install the hook
385 Commit editing and caveats
386 ==========================
388 A warning not to edit published (pushed) commits also appears in
389 documentation but it's repeated here anyway as it's very important.
391 It is possible to recover from forced push but it's PITA for the
392 entire team. Please avoid it.
394 To see what commits have not been published yet compare the head of the
395 branch with its upstream remote-tracking branch::
397 $ git log origin/master..
398 $ git log origin/v1..v1
400 For every branch that has an upstream remote-tracking branch git
401 maintains an alias @{upstream} (short version @{u}), so the commands
402 above can be given as::
407 To see the status of all branches::
411 To compare the status of local branches with a remote repo::
413 $ git remote show origin
415 Read `how to recover from upstream rebase
416 <https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase>`_.
417 It is in ``git help rebase``.
419 On the other hand don't be too afraid about commit editing. You can
420 safely edit, remove, reorder, combine and split commits that haven't
421 been pushed yet. You can even push commits to your own (backup) repo,
422 edit them later and force-push edited commits to replace what have
423 already been pushed. Not a problem until commits are in a public
424 or shared repository.
430 Whatever you do, don't panic. Almost anything in git can be undone.
433 git checkout: restore file's content
434 ------------------------------------
436 ``git checkout``, for example, can be used to restore the content of
437 file(s) to that one of a commit. Like this::
439 git checkout HEAD~ README
441 The commands restores the contents of README file to the last but one
442 commit in the current branch. By default the commit ID is simply HEAD;
443 i.e. ``git checkout README`` restores README to the latest commit.
445 (Do not use ``git checkout`` to view a content of a file in a commit,
446 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
449 git reset: remove (non-pushed) commits
450 --------------------------------------
452 ``git reset`` moves the head of the current branch. The head can be
453 moved to point to any commit but it's often used to remove a commit or
454 a few (preferably, non-pushed ones) from the top of the branch - that
455 is, to move the branch backward in order to undo a few (non-pushed)
458 ``git reset`` has three modes of operation - soft, hard and mixed.
459 Default is mixed. ProGit `explains
460 <https://git-scm.com/book/en/Git-Tools-Reset-Demystified>`_ the
461 difference very clearly. Bare repositories don't have indices or
462 working trees so in a bare repo only soft reset is possible.
468 Mixed mode reset with a path or paths can be used to unstage changes -
469 that is, to remove from index changes added with ``git add`` for
470 committing. See `The Book
471 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
472 about unstaging and other undo tricks.
475 git reflog: reference log
476 -------------------------
478 Removing commits with ``git reset`` or moving the head of a branch
479 sounds dangerous and it is. But there is a way to undo: another
480 reset back to the original commit. Git doesn't remove commits
481 immediately; unreferenced commits (in git terminology they are called
482 "dangling commits") stay in the database for some time (default is two
483 weeks) so you can reset back to it or create a new branch pointing to
486 For every move of a branch's head - with ``git commit``, ``git
487 checkout``, ``git fetch``, ``git pull``, ``git rebase``, ``git reset``
488 and so on - git stores a reference log (reflog for short). For every
489 move git stores where the head was. Command ``git reflog`` can be used
490 to view (and manipulate) the log.
492 In addition to the moves of the head of every branch git stores the
493 moves of the HEAD - a symbolic reference that (usually) names the
494 current branch. HEAD is changed with ``git checkout $BRANCH``.
496 By default ``git reflog`` shows the moves of the HEAD, i.e. the
497 command is equivalent to ``git reflog HEAD``. To show the moves of the
498 head of a branch use the command ``git reflog $BRANCH``.
500 So to undo a ``git reset`` lookup the original commit in ``git
501 reflog``, verify it with ``git show`` or ``git log`` and run ``git
502 reset $COMMIT_ID``. Git stores the move of the branch's head in
503 reflog, so you can undo that undo later again.
505 In a more complex situation you'd want to move some commits along with
506 resetting the head of the branch. Cherry-pick them to the new branch.
507 For example, if you want to reset the branch ``master`` back to the
508 original commit but preserve two commits created in the current branch
511 $ git branch save-master # create a new branch saving master
512 $ git reflog # find the original place of master
513 $ git reset $COMMIT_ID
514 $ git cherry-pick save-master~ save-master
515 $ git branch -D save-master # remove temporary branch
518 git revert: revert a commit
519 ---------------------------
521 ``git revert`` reverts a commit or commits, that is, it creates a new
522 commit or commits that revert(s) the effects of the given commits.
523 It's the only way to undo published commits (``git commit --amend``,
524 ``git rebase`` and ``git reset`` change the branch in
525 non-fast-forwardable ways so they should only be used for non-pushed
528 There is a problem with reverting a merge commit. ``git revert`` can
529 undo the code created by the merge commit but it cannot undo the fact
530 of merge. See the discussion `How to revert a faulty merge
531 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
534 One thing that cannot be undone
535 -------------------------------
537 Whatever you undo, there is one thing that cannot be undone -
538 overwritten uncommitted changes. Uncommitted changes don't belong to
539 git so git cannot help preserving them.
541 Most of the time git warns you when you're going to execute a command
542 that overwrites uncommitted changes. Git warns you when you try to
543 switch branches with ``git checkout``. It warns you when you're going
544 to rebase with non-clean working tree. It refuses to pull new commits
545 over non-committed files.
547 But there are commands that do exactly that - overwrite files in the
548 working tree. Commands like ``git checkout $PATHs`` or ``git reset
549 --hard`` silently overwrite files including your uncommitted changes.
551 With that in mind you can understand the stance "commit early, commit
552 often". Commit as often as possible. Commit on every save in your
553 editor or IDE. You can edit your commits before pushing - change,
554 reorder, combine, remove. But save your changes in git database,
555 either commit changes or at least stash them with ``git stash``.
561 Internet is full of heated discussions on the topic: "merge or
562 rebase?" Most of them are meaningless. When a DVCS is being used in a
563 big team with a big and complex project with many branches there is
564 simply no way to avoid merges. So the question's diminished to
565 "whether to use rebase, and if yes - when to use rebase?" Considering
566 that it is very much recommended not to rebase published commits the
567 question's diminished even further: "whether to use rebase on
570 That small question is for the team to decide. The author of the PEP
571 recommends to use rebase when pulling, i.e. always do ``git pull
572 --rebase`` or even configure automatic setup of rebase for every new
575 $ git config branch.autosetuprebase always
577 and configure rebase for existing branches::
579 $ git config branch.$NAME.rebase true
583 $ git config branch.v1.rebase true
584 $ git config branch.master.rebase true
586 After that ``git pull origin master`` becomes equivalent to ``git pull
587 --rebase origin master``.
589 In case when merge is preferred it is recommended to create new
590 commits in a separate feature or topic branch while using rebase to
591 update the mainline branch. When the topic branch is ready merge it
592 into mainline. To avoid a tedious task of resolving large number of
593 conflicts at once you can merge the topic branch to the mainline from
594 time to time and switch back to the topic branch to continue working
595 on it. The entire workflow would be something like::
597 $ git checkout -b issue-42 # create a new issue branch and switch to it
598 ...edit/test/commit...
599 $ git checkout master
600 $ git pull --rebase origin master # update master from the upstream
602 $ git branch -d issue-42 # delete the topic branch
603 $ git push origin master
605 When the topic branch is deleted only the label is removed, commits
606 are stayed in the database, they are now merged into master::
608 o--o--o--o--o--M--< master - the mainline branch
610 --*--*--* - the topic branch, now unnamed
612 The topic branch is deleted to avoid cluttering branch namespace with
613 small topic branches. Information on what issue was fixed or what
614 feature was implemented should be in the commit messages.
620 Git has a builtin merge strategy for what Python core developers call
623 $ git merge -s ours v1 # null-merge v1 into master
626 Advanced configuration
627 ======================
632 Git has builtin mechanisms to handle line endings between platforms
633 with different EOL styles. To allow git to do CRLF conversion assign
634 ``text`` attribute to files using `.gitattributes
635 <https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html>`_.
636 For files that have to have specific line ending assign ``eol``
637 attribute. For binary files the attribute is, naturally, ``binary``.
647 To check what attributes git uses for files use ``git check-attr``
648 command. For example::
650 $ git check-attr -a -- \*.py
659 Staging area aka index aka cache is a distinguishing feature of git.
660 Staging area is where git collects patches before committing them.
661 Separation between collecting patches and commit phases provides a
662 very useful feature of git: you can review collected patches before
663 commit and even edit them - remove some hunks, add new hunks and
666 To add files to the index use ``git add``. Collecting patches before
667 committing means you need to do that for every change, not only to add
668 new (untracked) files. To simplify committing in case you just want to
669 commit everything without reviewing run ``git commit --all`` (or just
670 ``-a``) - the command adds every changed tracked file to the index and
671 then commit. To commit a file or files regardless of patches collected
672 in the index run ``git commit [--only|-o] -- $FILE...``.
674 To add hunks of patches to the index use ``git add --patch`` (or just
675 ``-p``). To remove collected files from the index use ``git reset HEAD
676 -- $FILE...`` To add/inspect/remove collected hunks use ``git add
677 --interactive`` (``-i``).
679 To see the diff between the index and the last commit (i.e., collected
680 patches) use ``git diff --cached``. To see the diff between the
681 working tree and the index (i.e., uncollected patches) use just ``git
682 diff``. To see the diff between the working tree and the last commit
683 (i.e., both collected and uncollected patches) run ``git diff HEAD``.
686 <https://git.wiki.kernel.org/index.php/WhatIsTheIndex>`_ and
687 `IndexCommandQuickref
688 <https://git.wiki.kernel.org/index.php/IndexCommandQuickref>`_ in Git
695 Rerere is a mechanism that helps to resolve repeated merge conflicts.
696 The most frequent source of recurring merge conflicts are topic
697 branches that are merged into mainline and then the merge commits are
698 removed; that's often performed to test the topic branches and train
699 rerere; merge commits are removed to have clean linear history and
700 finish the topic branch with only one last merge commit.
702 Rerere works by remembering the states of tree before and after a
703 successful commit. That way rerere can automatically resolve conflicts
704 if they appear in the same files.
706 Rerere can be used manually with ``git rerere`` command but most often
707 it's used automatically. Enable rerere with these commands in a
710 $ git config rerere.enabled true
711 $ git config rerere.autoupdate true
713 You don't need to turn rerere on globally - you don't want rerere in
714 bare repositories or repositories without branches; you only need
715 rerere in repos where you often perform merges and resolve merge
718 See `Rerere <https://git-scm.com/book/en/Git-Tools-Rerere>`_ in The
725 Git object database and other files/directories under ``.git`` require
726 periodic maintenance and cleanup. For example, commit editing left
727 unreferenced objects (dangling objects, in git terminology) and these
728 objects should be pruned to avoid collecting cruft in the DB. The
729 command ``git gc`` is used for maintenance. Git automatically runs
730 ``git gc --auto`` as a part of some commands to do quick maintenance.
731 Users are recommended to run ``git gc --aggressive`` from time to
732 time; ``git help gc`` recommends to run it every few hundred
733 changesets; for more intensive projects it should be something like
734 once a week and less frequently (biweekly or monthly) for lesser
737 ``git gc --aggressive`` not only removes dangling objects, it also
738 repacks object database into indexed and better optimized pack(s); it
739 also packs symbolic references (branches and tags). Another way to do
740 it is to run ``git repack``.
742 There is a well-known `message
743 <https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html>`_ from Linus
744 Torvalds regarding "stupidity" of ``git gc --aggressive``. The message
745 can safely be ignored now. It is old and outdated, ``git gc
746 --aggressive`` became much better since that time.
748 For those who still prefer ``git repack`` over ``git gc --aggressive``
749 the recommended parameters are ``git repack -a -d -f --depth=20
750 --window=250``. See `this detailed experiment
751 <http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html>`_
752 for explanation on the effects of these parameters.
754 From time to time run ``git fsck [--strict]`` to verify integrity of
755 the database. ``git fsck`` may produce a list of dangling objects;
756 that's not an error, just a reminder to perform regular maintenance.
762 Command-line options and arguments
763 ----------------------------------
766 <https://www.kernel.org/pub/software/scm/git/docs/gitcli.html>`_
767 recommends not to combine short options/flags. Most of the times it
768 works: ``git commit -av`` works perfectly, but there are situations
769 when it doesn't. E.g., ``git log -p -5`` cannot be combined as ``git
772 Some options have arguments, some even have default arguments. In that
773 case the argument for such option must be spelled in a sticky way:
774 ``-Oarg``, never ``-O arg`` because for an option that has a default
775 argument the latter means "use default value for option ``-O`` and
776 pass ``arg`` further to the option parser". For example, ``git grep``
777 has an option ``-O`` that passes found files to a program; default
778 program for ``-O`` is pager (usually ``less``), but you can use your
781 $ git grep -Ovim # but not -O vim
783 BTW, there is a difference between running ``git grep -O`` and ``git
784 grep -Oless`` - in the latter case ``git grep`` passes ``+/pattern``
791 It's a bit hard to type ``git rebase --interactive --preserve-merges
792 HEAD~5`` manually even for those who are happy to use command-line,
793 and this is where shell completion is of great help. Bash/zsh come
794 with programmable completion, often automatically preinstalled and
795 enabled, so if you have bash/zsh and git installed, chances are you
796 are already done - just go and use it at the command-line.
798 If you don't have necessary bits preinstalled, install and enable
799 bash_completion package. If you want to upgrade your git completion to
800 the latest and greatest download necessary file from `git contrib
801 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion>`_.
803 Git-for-windows comes with git-bash for which bash completion is
804 installed and enabled.
810 For command-line lovers shell prompt can carry a lot of useful
811 information. To include git information in the prompt use
813 <https://git.kernel.org/cgit/git/git.git/tree/contrib/completion/git-prompt.sh>`_.
814 Read the detailed instructions in the file.
816 Search the Net for "git prompt" to find other prompt variants.
822 The simplest way to publish a repository or a group of repositories is
823 ``git daemon``. The daemon provides anonymous access, by default it is
824 read-only. The repositories are accessible by git protocol (git://
825 URLs). Write access can be enabled but the protocol lacks any
826 authentication means, so it should be enabled only within a trusted
827 LAN. See ``git help daemon`` for details.
829 Git over ssh provides authentication and repo-level authorisation as
830 repositories can be made user- or group-writeable (see parameter
831 ``core.sharedRepository`` in ``git help config``). If that's too
832 permissive or too restrictive for some project's needs there is a
833 wrapper `gitolite <http://gitolite.com/gitolite/index.html>`_ that can
834 be configured to allow access with great granularity; gitolite has a
835 lot of documentation.
837 Web interface to browse repositories can be created using `gitweb
838 <https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ and `cgit
839 <http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
840 Perl and C). In addition to web interface both provide read-only dumb
841 http access for git (http(s):// URLs).
843 There are also more advanced web-based development environments that
844 include ability to manage users, groups and projects; private, group
845 and public repositories; and often include issue trackers, wiki pages,
846 pull requests and other tools for development and communication. Among
847 these environments are `Kallithea <https://kallithea-scm.org/>`_ and
848 `pagure <https://pagure.io/>`_, both are written in Python; pagure was
849 written by Fedora developers and is being used to develop some Fedora
850 projects. `Gogs <http://gogs.io/>`_ is written in Go; there is a fork
851 `Gitea <http://gitea.io/>`_.
853 And last but not least `Gitlab <https://about.gitlab.com/>`_. It's
854 perhaps the most advanced git web-based development environment.
855 Written in Ruby, community edition is free and open source (MIT
859 From Mercurial to git
860 =====================
862 There are many tools to convert Mercurial repositories to git. The
863 most famous are, perhaps, `hg-git <https://hg-git.github.io/>`_ and
864 `fast-export <http://repo.or.cz/w/fast-export.git>`_ (many years ago
865 it was known under the name ``hg2git``).
867 But a better tool, perhaps the best, is `git-remote-hg
868 <https://github.com/felipec/git-remote-hg>`_. It provides transparent
869 bidirectional access (pull and push) to Mercurial repositories from
870 git. The author wrote a `comparison of alternatives
871 <https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives>`_
872 that seems to be mostly unbiased.
874 To use git-remote-hg, install or clone it, add to your PATH (or copy
875 script ``git-remote-hg`` to a directory that's already in PATH) and
876 prepend ``hg::`` to Mercurial URLs. For example::
878 $ git clone https://github.com/felipec/git-remote-hg.git
879 $ PATH=$PATH:"`pwd`"/git-remote-hg
880 $ git clone hg::https://hg.python.org/peps/ PEPs
882 To work with the repository just use regular git commands including
883 ``git fetch/pull/push``.
885 To start converting your Mercurial habits to git see the page
886 `Mercurial for Git users
887 <https://mercurial.selenic.com/wiki/GitConcepts>`_ at Mercurial wiki.
888 At the second half of the page there is a table that lists
889 corresponding Mercurial and git commands. Should work perfectly in
896 This document has been placed in the public domain.
903 indent-tabs-mode: nil
904 sentence-end-double-space: t
908 vim: set fenc=us-ascii tw=70 :