hg-git: README.md annotate

annotate README.md @ 328:5875262c92ac

README: reword clone command section Remove the duplicated "hg clone ..." command, favouring the block instance over the inline one to emphasize focus on the command. Also say "hg-git would clone..." instead of "it would clone..." to minimize disambiguity. While we're at it, wrap the lines to 80 characters.

author	Tay Ray Chuan <rctay89@gmail.com>
date	Mon, 17 May 2010 19:55:17 +0800
parents	f8a94616b957
children	3f0ceaf30344

rev	line source
46 0bfcd0c06b8e clarified in the readme that this is still alpha Scott Chacon <schacon@gmail.com> parents: 45 diff changeset	1 Warning: This plugin is not yet stabilized. Use to help me identify bugs, but it will be a few weeks before its fully stable.
0bfcd0c06b8e clarified in the readme that this is still alpha Scott Chacon <schacon@gmail.com> parents: 45 diff changeset	2
163 74f38b519887 got octomerges working Scott Chacon <schacon@gmail.com> parents: 152 diff changeset	3 Project status as of 5/27: Pretty solid, but a bit slow - can losslessly convert most major scenarios and can handle projects up to several thousand commits. Submodules in Git are not handled. See TODO.txt for full list of things I'm working on.
111 c00bee6c5de7 status update Scott Chacon <schacon@gmail.com> parents: 46 diff changeset	4
c00bee6c5de7 status update Scott Chacon <schacon@gmail.com> parents: 46 diff changeset	5
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	6 Hg-Git Mercurial Plugin
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	7 =======================
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	8
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	9 This is the Hg-Git plugin for Mercurial, adding the ability to push and pull to/from a Git server repository from Hg. This means you can collaborate on Git based projects from Hg, or use a Git server as a collaboration point for a team with developers using both Git and Hg.
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	10
115 e28e669e2010 readme update - added sverre and fixed some stuff Scott Chacon <schacon@gmail.com> parents: 114 diff changeset	11 The Hg-Git plugin can convert commits/changesets losslessly from one system to another, so you can push via an Hg repository and another Hg client can pull it and their changeset node ids will be identical - Mercurial data does not get lost in translation. It is intended that Hg users may wish to use this to collaborate even if no Git users are involved in the project, and it may even provide some advantages if you're using Bookmarks (see below).
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	12
45 a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	13 Dependencies
a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	14 ============
a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	15
224 80d67ae190df port to upstream dulwich Abderrahim Kitouni <a.kitouni@gmail.com> parents: 200 diff changeset	16 This plugin is implemented entirely in Python - there are no Git binary dependencies, you do not need to have Git installed on your system. The only dependencies are Mercurial and Dulwich. The plugin is known to work on Hg versions 1.1 through 1.3 and requires at least Dulwich 0.3.2.
45 a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	17
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	18 Commands
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	19 =========
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	20
328 5875262c92ac README: reword clone command section Tay Ray Chuan <rctay89@gmail.com> parents: 327 diff changeset	21 You can clone a Git repository from Hg by running `hg clone [url]`. For
5875262c92ac README: reword clone command section Tay Ray Chuan <rctay89@gmail.com> parents: 327 diff changeset	22 example, if you were to run
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	23
327 f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	24 $ hg clone git://github.com/schacon/hg-git.git
197 11235deb86fc README: Added information about the git+ssh:// url format. Arne Babenhauserheide <bab@draketo.de> parents: 192 diff changeset	25
328 5875262c92ac README: reword clone command section Tay Ray Chuan <rctay89@gmail.com> parents: 327 diff changeset	26 hg-git would clone the repository down into the directory 'munger.git', then
5875262c92ac README: reword clone command section Tay Ray Chuan <rctay89@gmail.com> parents: 327 diff changeset	27 convert it to an Hg repository for you.
5875262c92ac README: reword clone command section Tay Ray Chuan <rctay89@gmail.com> parents: 327 diff changeset	28
200 dfed3bd84184 README: minor fixes Abderrahim Kitouni <a.kitouni@gmail.com> parents: 197 diff changeset	29 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 to a format with explicit protocol prefix (mind the switch from colon to slash after the host!):
dfed3bd84184 README: minor fixes Abderrahim Kitouni <a.kitouni@gmail.com> parents: 197 diff changeset	30
327 f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	31 $ git clone git@github.com:schacon/hg-git.git
f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	32 $ hg clone git+ssh://git@github.com/schacon/hg-git.git
200 dfed3bd84184 README: minor fixes Abderrahim Kitouni <a.kitouni@gmail.com> parents: 197 diff changeset	33
192 03ef61d6882b Updated the readme some more... Arne Babenhauserheide <bab@draketo.de> parents: 191 diff changeset	34 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:
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	35
327 f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	36 $ cd hg-git # (an Hg repository)
f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	37 $ # edit .hg/hgrc and add the target git url in the paths section
f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	38 $ hg push
197 11235deb86fc README: Added information about the git+ssh:// url format. Arne Babenhauserheide <bab@draketo.de> parents: 192 diff changeset	39
11235deb86fc README: Added information about the git+ssh:// url format. Arne Babenhauserheide <bab@draketo.de> parents: 192 diff changeset	40 This will convert all your Hg data into Git objects and push them up to the Git server.
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	41
191 c3aeeff8fb29 Updated the readme to include the usage of [paths]. Arne Babenhauserheide <bab@draketo.de> parents: 163 diff changeset	42 Now that you have an Hg repository that can push/pull to/from a Git repository, you can fetch updates with `hg pull`.
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	43
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	44 $ hg pull
197 11235deb86fc README: Added information about the git+ssh:// url format. Arne Babenhauserheide <bab@draketo.de> parents: 192 diff changeset	45
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	46 That will pull down any commits that have been pushed to the server in the meantime and give you a new head that you can merge in.
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	47
319 3ab3765db5bc README.md: Improve Mercurial to Git conversion description. Simon Ruderich <simon@ruderich.org> parents: 318 diff changeset	48 Hg-Git can also be used to convert a Mercurial repository to Git. As Dulwich doesn't support local repositories yet, the easiest way is to setup up a local SSH server. Then use the following commands to convert the repository (it assumes your running this in $HOME).
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	49
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	50 $ mkdir git-repo; cd git-repo; git init; cd ..
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	51 $ cd hg-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	52 $ hg bookmarks hg
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	53 $ hg push git+ssh://localhost:git-repo
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	54
319 3ab3765db5bc README.md: Improve Mercurial to Git conversion description. Simon Ruderich <simon@ruderich.org> parents: 318 diff changeset	55 The hg bookmark is necessary to prevent problems as otherwise hg-git pushes to the currently checked out branch confusing Git. This will create a branch named hg in the Git repository. To get the changes in master use the following command (only necessary in the first run, later just use git merge or rebase).
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	56
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	57 $ cd git-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	58 $ git checkout -b master hg
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	59
319 3ab3765db5bc README.md: Improve Mercurial to Git conversion description. Simon Ruderich <simon@ruderich.org> parents: 318 diff changeset	60 To import new changesets into the Git repository just rerun the hg push command and then use git merge or git rebase in your Git repository.
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	61
f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	62
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	63 Hg Bookmarks Integration
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	64 ========================
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	65
200 dfed3bd84184 README: minor fixes Abderrahim Kitouni <a.kitouni@gmail.com> parents: 197 diff changeset	66 If you have the bookmarks extension enabled, Hg-Git will use it. It will push your bookmarks up to the Git server as branches and will pull Git branches down and set them up as bookmarks.
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	67
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	68 This is actually pretty cool, since you can use this extension to transfer your Hg bookmarks via the Git protocol, rather than having to scp them, as the Hg transfer protocol does not currently support transferring bookmarks.
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	69
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	70 Installing
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	71 ==========
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	72
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	73 Clone this repository somewhere and make the 'extensions' section in your `~/.hgrc` file look something like this:
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	74
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	75 [extensions]
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	76 hgext.bookmarks =
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	77 hggit = [path-to]/hg-git/hggit
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	78
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	79 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.
44 234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	80
234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	81 Authors
234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	82 ========
234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	83
234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	84 * Scott Chacon <schacon@gmail.com> - main development
255 b0d3d6330b80 Updated readme with more complete author list and some corrected docs. Augie Fackler <durin42@gmail.com> parents: 224 diff changeset	85 * Augie Fackler <durin42@gmail.com> - testing and moral support, janitor
115 e28e669e2010 readme update - added sverre and fixed some stuff Scott Chacon <schacon@gmail.com> parents: 114 diff changeset	86 * Sverre Rabbelier <sverre@rabbelier.nl> - gexport, mode and i18n stuff and misc fixes
255 b0d3d6330b80 Updated readme with more complete author list and some corrected docs. Augie Fackler <durin42@gmail.com> parents: 224 diff changeset	87 * Abderrahim Kitouni <a.kitouni@gmail.com> - more "mercurialistic" UI
b0d3d6330b80 Updated readme with more complete author list and some corrected docs. Augie Fackler <durin42@gmail.com> parents: 224 diff changeset	88 * Kevin Bullock <kbullock@ringworld.org> - proper packaging for PyPI
b0d3d6330b80 Updated readme with more complete author list and some corrected docs. Augie Fackler <durin42@gmail.com> parents: 224 diff changeset	89
45 a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	90 * Dulwich Developers - most of this code depends on the awesome work they did.
255 b0d3d6330b80 Updated readme with more complete author list and some corrected docs. Augie Fackler <durin42@gmail.com> parents: 224 diff changeset	91
44 234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	92 Sponsorship
234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	93 ===========
234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	94
45 a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	95 GitHub let me (Scott) work on this full time for several days, which is why this got done at all. If you're looking for a free Git host to push your open source Hg projects to, do try us out (http://github.com).

Mercurial > hg-git

annotate README.md @ 328:5875262c92ac