git-remote-hg can be copied to a dir in PATH

[git-wiki.git] / pep-git.txt

diff --git a/pep-git.txt b/pep-git.txt
index 15413e37024b934dc6c3819c6b1b2b120b173925..f9cae0363c598689c42138de724a43bd2431f002 100644 (file)
--- a/pep-git.txt
+++ b/pep-git.txt
@@ -14,7 +14,7 @@ Abstract
 
 This Informational PEP collects information about git. There is, of
 course, a lot of documentation for git, so the PEP concentrates on
 
 This Informational PEP collects information about git. There is, of
 course, a lot of documentation for git, so the PEP concentrates on

-more complex issues, scenarios and topics.
+more complex issues, scenarios and examples.

 
 The plan is to extend the PEP in the future collecting information
 about equivalence of Mercurial and git scenarios to help migrating
 
 The plan is to extend the PEP in the future collecting information
 about equivalence of Mercurial and git scenarios to help migrating


@@ -30,6 +30,7 @@ Documentation
 Git is accompanied with a lot of documentation, both online and
 offline.
 
 Git is accompanied with a lot of documentation, both online and
 offline.
 

+

 Documentation for starters
 --------------------------
 
 Documentation for starters
 --------------------------
 


@@ -45,6 +46,7 @@ Git Tutorial: `part 1
 `Git workflows
 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
 
 `Git workflows
 <https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html>`_.
 

+

 Advanced documentation
 ----------------------
 
 Advanced documentation
 ----------------------
 


@@ -59,6 +61,7 @@ many different languages. Download Russian translation from `GArik
 
 `Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
 
 
 `Git Wiki <https://git.wiki.kernel.org/index.php/Main_Page>`_.
 

+

 Offline documentation
 ---------------------
 
 Offline documentation
 ---------------------
 


@@ -92,6 +95,7 @@ written in Python and GPL licensed. Linux, Windows, MacOS X.
 `TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
 to Git based on TortoiseSVN; open source.
 
 `TortoiseGit <https://tortoisegit.org/>`_ is a Windows Shell Interface
 to Git based on TortoiseSVN; open source.
 

+

 Initial configuration
 ---------------------
 
 Initial configuration
 ---------------------
 


@@ -114,7 +118,7 @@ local repo has two branches ``v1`` and ``master``. For most examples
 the currently checked out branch is ``master``. That is, it's assumed
 you have done something like that::
 
 the currently checked out branch is ``master``. That is, it's assumed
 you have done something like that::
 

-    $ git clone http://git.python.org/python.git
+    $ git clone https://git.python.org/python.git

     $ cd python
     $ git branch v1 origin/v1
 
     $ cd python
     $ git branch v1 origin/v1
 


@@ -128,7 +132,7 @@ remotes/origin/v1 as its upstream remote-tracking branch.
 
 The same result can be achieved with commands::
 
 
 The same result can be achieved with commands::
 

-    $ git clone -b v1 http://git.python.org/python.git
+    $ git clone -b v1 https://git.python.org/python.git

     $ cd python
     $ git checkout --track origin/master
 
     $ cd python
     $ git checkout --track origin/master
 


@@ -177,14 +181,15 @@ fast-forwards, merges or rebases local branches.
 
 When you do an initial clone like this::
 
 
 When you do an initial clone like this::
 

-    $ git clone -b v1 http://git.python.org/python.git
+    $ git clone -b v1 https://git.python.org/python.git

 
 

-git clones remote repository ``http://git.python.org/python.git`` to
+git clones remote repository ``https://git.python.org/python.git`` to

 directory ``python``, creates a remote named ``origin``, creates
 remote-tracking branches, creates a local branch ``v1``, configure it
 to track upstream remotes/origin/v1 branch and checks out ``v1`` into
 the working directory.
 
 directory ``python``, creates a remote named ``origin``, creates
 remote-tracking branches, creates a local branch ``v1``, configure it
 to track upstream remotes/origin/v1 branch and checks out ``v1`` into
 the working directory.
 

+

 Updating local and remote-tracking branches
 -------------------------------------------
 
 Updating local and remote-tracking branches
 -------------------------------------------
 


@@ -362,6 +367,7 @@ Or push all tags at once::
 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
 after they have been published.
 
 Don't move tags with ``git tag -f`` or remove tags with ``git tag -d``
 after they have been published.
 

+

 Private information
 '''''''''''''''''''
 
 Private information
 '''''''''''''''''''
 


@@ -423,6 +429,7 @@ Undo
 
 Whatever you do, don't panic. Almost anything in git can be undone.
 
 
 Whatever you do, don't panic. Almost anything in git can be undone.
 

+

 git checkout: restore file's content
 ------------------------------------
 
 git checkout: restore file's content
 ------------------------------------
 


@@ -438,6 +445,7 @@ i.e. ``git checkout README`` restores README to the latest commit.
 (Do not use ``git checkout`` to view a content of a file in a commit,
 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
 
 (Do not use ``git checkout`` to view a content of a file in a commit,
 use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``).
 

+

 git reset: remove (non-pushed) commits
 --------------------------------------
 
 git reset: remove (non-pushed) commits
 --------------------------------------
 


@@ -453,6 +461,7 @@ Default is mixed. ProGit `explains
 difference very clearly. Bare repositories don't have indices or
 working trees so in a bare repo only soft reset is possible.
 
 difference very clearly. Bare repositories don't have indices or
 working trees so in a bare repo only soft reset is possible.
 

+

 Unstaging
 '''''''''
 
 Unstaging
 '''''''''
 


@@ -462,6 +471,7 @@ committing. See `The Book
 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
 about unstaging and other undo tricks.
 
 <https://git-scm.com/book/en/Git-Basics-Undoing-Things>`_ for details
 about unstaging and other undo tricks.
 

+

 git reflog: reference log
 -------------------------
 
 git reflog: reference log
 -------------------------
 


@@ -504,6 +514,7 @@ do something like::
     $ git cherry-pick save-master~ save-master
     $ git branch -D save-master # remove temporary branch
 
     $ git cherry-pick save-master~ save-master
     $ git branch -D save-master # remove temporary branch
 

+

 git revert: revert a commit
 ---------------------------
 
 git revert: revert a commit
 ---------------------------
 


@@ -519,6 +530,7 @@ undo the code created by the merge commit but it cannot undo the fact
 of merge. See the discussion `How to revert a faulty merge
 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
 
 of merge. See the discussion `How to revert a faulty merge
 <https://www.kernel.org/pub/software/scm/git/docs/howto/revert-a-faulty-merge.html>`_.
 

+

 One thing that cannot be undone
 -------------------------------
 
 One thing that cannot be undone
 -------------------------------
 


@@ -772,6 +784,7 @@ BTW, there is a difference between running ``git grep -O`` and ``git
 grep -Oless`` - in the latter case ``git grep`` passes ``+/pattern``
 option to less.
 
 grep -Oless`` - in the latter case ``git grep`` passes ``+/pattern``
 option to less.
 

+

 bash/zsh completion
 -------------------
 
 bash/zsh completion
 -------------------
 


@@ -790,6 +803,7 @@ the latest and greatest download necessary file from `git contrib
 Git-for-windows comes with git-bash for which bash completion is
 installed and enabled.
 
 Git-for-windows comes with git-bash for which bash completion is
 installed and enabled.
 

+

 bash/zsh prompt
 ---------------
 
 bash/zsh prompt
 ---------------
 


@@ -820,29 +834,55 @@ wrapper `gitolite <http://gitolite.com/gitolite/index.html>`_ that can
 be configured to allow access with great granularity; gitolite has a
 lot of documentation.
 
 be configured to allow access with great granularity; gitolite has a
 lot of documentation.
 

-TODO: gitweb; cgit; Kallithea; pagure; gogs and gitea; gitlab.
+Web interface to browse repositories can be created using `gitweb
+<https://git.kernel.org/cgit/git/git.git/tree/gitweb>`_ and `cgit
+<http://git.zx2c4.com/cgit/about/>`_. Both are CGI scripts (written in
+Perl and C). In addition to web interface both provide read-only dumb
+http access for git (http(s):// URLs).

 
 

-https://git.kernel.org/cgit/git/git.git/tree/gitweb
+There are also more advanced web-based development environments that
+include ability to manage users, groups and projects; private, group
+and public repositories; and often include issue trackers, wiki pages,
+pull requests and other tools for development and communication. Among
+these environments are `Kallithea <https://kallithea-scm.org/>`_ and
+`pagure <https://pagure.io/>`_, both are written in Python; pagure was
+written by Fedora developers and is being used to develop some Fedora
+projects. `Gogs <http://gogs.io/>`_ is written in Go; there is a fork
+`Gitea <http://gitea.io/>`_.

 
 

-http://git.zx2c4.com/cgit/about/
+And last but not least `Gitlab <https://about.gitlab.com/>`_. It's
+perhaps the most advanced git web-based development environment.
+Written in Ruby, community edition is free and open source (MIT
+license).

 
 

-https://kallithea-scm.org/

 
 

-https://pagure.io/
-
-http://gogs.io/ and http://gitea.io/
+From Mercurial to git
+=====================

 
 

-https://about.gitlab.com/
+There are many tools to convert Mercurial repositories to git. The
+most famous are, perhaps, `hg-git <https://hg-git.github.io/>`_ and
+`fast-export <http://repo.or.cz/w/fast-export.git>`_ (many years ago
+it was known under the name ``hg2git``).

 
 

+But a better tool, perhaps the best, is `git-remote-hg
+<https://github.com/felipec/git-remote-hg>`_. It provides transparent
+bidirectional access (pull and push) to Mercurial repositories from
+git. The author wrote a `comparison of alternatives
+<https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives>`_
+that seems to be mostly unbiased.

 
 

-From Mercurial to git
-=====================
+To use git-remote-hg, install or clone it, add to your PATH (or copy
+script ``git-remote-hg`` to a directory that's already in PATH) and
+prepend ``hg::`` to Mercurial URLs. For example::

 
 

-Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts
+    $ git clone https://github.com/felipec/git-remote-hg.git
+    $ PATH=$PATH:"`pwd`"/git-remote-hg
+    $ git clone hg::https://hg.python.org/peps/ PEPs

 
 

-https://github.com/felipec/git-remote-hg
+To work with the repository just use normal ``git fetch/pull/push``
+commands.

 
 

-https://hg-git.github.io/
+Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts

 
 
 References
 
 
 References