Mercurial > hg-git

changeset 481:9df1741f3977

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
help: add additional help topics
author David M. Carr <david@carrclan.us>
date Wed, 22 Aug 2012 23:39:45 -0400
parents c88e8a88c5f6
children 00d591868a2f
files README.md hggit/__init__.py hggit/help/git.rst setup.py tests/test-help tests/test-help.out
diffstat 6 files changed, 102 insertions(+), 8 deletions(-) [+]
line wrap: on
line diff
--- a/README.md	Wed Aug 22 23:39:45 2012 -0400
+++ b/README.md	Wed Aug 22 23:39:45 2012 -0400
@@ -30,13 +30,13 @@
 Usage
 =====
 
-You can clone a Git repository from Hg by running `hg clone [url]`.  For
+You can clone a Git repository from Hg by running `hg clone <url> [dest]`.  For
 example, if you were to run
 
     $ hg clone git://github.com/schacon/hg-git.git
 
-hg-git would clone the repository down into the directory 'munger.git', then
-convert it to an Hg repository for you.
+Hg-Git would clone the repository and convert it to an Hg repository
+for you.
 
 If you want to clone a github repository for later pushing (or any
 other repository you access via ssh), you need to convert the ssh url
@@ -55,16 +55,16 @@
 
     $ hg clone git+ssh://git@github.com/schacon/hg-git.git
 
-If you are starting from an existing Hg repository, you have to setup
-a Git repository somewhere that you have push access to, add it as
-default path or default-push path in your .hg/hgrc and then run `hg
-push` from within your project.  For example:
+If you are starting from an existing Hg repository, you have to set up
+a Git repository somewhere that you have push access to, add a path entry
+for it in your .hg/hgrc file, and then run `hg push [name]` from within
+your repository.  For example:
 
     $ cd hg-git # (an Hg repository)
     $ # edit .hg/hgrc and add the target git url in the paths section
     $ hg push
 
-This will convert all your Hg data into Git objects and push them up to the Git server.
+This will convert all your Hg data into Git objects and push them to the Git server.
 
 Now that you have an Hg repository that can push/pull to/from a Git
 repository, you can fetch updates with `hg pull`.
@@ -140,6 +140,17 @@
 That will enable the Hg-Git extension for you.  The bookmarks section
 is not compulsory, but it makes some things a bit nicer for you.
 
+This plugin is currently tested against the following Mercurial versions:
+ * 1.5.4
+ * 1.6.4
+ * 1.7.5
+ * 1.8.4
+ * 1.9.3
+ * 2.0.2
+ * 2.1.2
+ * 2.2.3
+ * 2.3
+
 Configuration
 =============
 
--- a/hggit/__init__.py	Wed Aug 22 23:39:45 2012 -0400
+++ b/hggit/__init__.py	Wed Aug 22 23:39:45 2012 -0400
@@ -13,8 +13,11 @@
 project that is in Git.  A bridger of worlds, this plugin be.
 
 Try hg clone git:// or hg clone git+ssh://
+
+For more information and instructions, see :hg:`help git`
 '''
 
+from bisect import insort
 import inspect
 import os
 
@@ -22,6 +25,7 @@
 from mercurial import commands
 from mercurial import demandimport
 from mercurial import extensions
+from mercurial import help
 from mercurial import hg
 from mercurial import localrepo
 from mercurial import util as hgutil
@@ -87,6 +91,16 @@
 if getattr(hg, 'addbranchrevs', False):
     extensions.wrapfunction(hg, 'addbranchrevs', safebranchrevs)
 
+def extsetup():
+    helpdir = os.path.join(os.path.dirname(__file__), 'help')
+    entry = (['git'], _("Working with Git Repositories"),
+        lambda: open(os.path.join(helpdir, 'git.rst')).read())
+    # in 1.6 and earler the help table is a tuple
+    if getattr(help.helptable, 'extend', None):
+        insort(help.helptable, entry)
+    else:
+        help.helptable = help.helptable + (entry,)
+
 def reposetup(ui, repo):
     if not isinstance(repo, gitrepo.gitrepo):
         klass = hgrepo.generate_repo_subclass(repo.__class__)
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/hggit/help/git.rst	Wed Aug 22 23:39:45 2012 -0400
@@ -0,0 +1,54 @@
+Basic Use
+---------
+
+You can clone a Git repository from Hg by running `hg clone <url> [dest]`.
+For example, if you were to run::
+
+ $ hg clone git://github.com/schacon/hg-git.git
+
+Hg-Git would clone the repository and convert it to an Hg repository for
+you. There are a number of different protocols that can be used for Git
+repositories. Examples of Git repository URLs include::
+
+  https://github.com/schacon/hg-git.git
+  http://code.google.com/p/guava-libraries
+  ssh://git@github.com:schacon/hg-git.git
+  git://github.com/schacon/hg-git.git
+
+For protocols other than git://, it isn't clear whether these should be
+interpreted as Mercurial or Git URLs. Thus, to specify that a URL should
+use Git, prepend the URL with "git+". For example, an HTTPS URL would
+start with "git+https://". Also, note that Git doesn't require the
+specification of the protocol for SSH, but Mercurial does.
+
+If you are starting from an existing Hg repository, you have to set up a
+Git repository somewhere that you have push access to, add a path entry
+for it in your .hg/hgrc file, and then run `hg push [name]` from within
+your repository. For example::
+
+ $ cd hg-git # (an Hg repository)
+ $ # edit .hg/hgrc and add the target Git URL in the paths section
+ $ hg push
+
+This will convert all your Hg data into Git objects and push them to the
+Git server.
+
+Pulling new revisions into a repository is the same as from any other
+Mercurial source. Within the earlier examples, the following commands are
+all equivalent::
+
+ $ hg pull
+ $ hg pull default
+ $ hg pull git://github.com/schacon/hg-git.git
+
+Git branches are exposed in Hg as bookmarks, while Git remotes are exposed
+as Hg local tags.  See `hg help bookmarks` and `hg help tags` for further
+information.
+
+Limitations
+-----------
+
+- Cloning/pushing/pulling local Git repositories is not supported (due to
+  lack of support in Dulwich)
+- The `hg incoming` and `hg outgoing` commands are not currently
+  supported.
\ No newline at end of file
--- a/setup.py	Wed Aug 22 23:39:45 2012 -0400
+++ b/setup.py	Wed Aug 22 23:39:45 2012 -0400
@@ -19,5 +19,6 @@
     keywords='hg git mercurial',
     license='GPLv2',
     packages=['hggit'],
+    package_data={ 'hggit': ['help/git.rst'] },
     install_requires=['dulwich>=0.8.0'],
 )
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tests/test-help	Wed Aug 22 23:39:45 2012 -0400
@@ -0,0 +1,10 @@
+#!/bin/sh
+
+# Tests that the various help files are properly registered
+
+echo "[extensions]" >> $HGRCPATH
+echo "hggit=$(echo $(dirname $(dirname $0)))/hggit" >> $HGRCPATH
+
+hg help | grep 'git' | sed 's/  */ /g'
+hg help hggit | grep 'help git' | sed 's/:hg:`help git`/"hg help git"/g'
+hg help git | grep 'Working with Git Repositories'
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tests/test-help.out	Wed Aug 22 23:39:45 2012 -0400
@@ -0,0 +1,4 @@
+ hggit push and pull from a Git server
+ git Working with Git Repositories
+For more information and instructions, see "hg help git"
+Working with Git Repositories