Mercurial > hg > hg-git

annotate README.md @ 327:f8a94616b957

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
README: prefix commands with dollar sign
author Tay Ray Chuan <rctay89@gmail.com>
date Mon, 17 May 2010 19:50:58 +0800
parents 62315903f88b
children 5875262c92ac
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
192
03ef61d6882b Updated the readme some more...
Arne Babenhauserheide <bab@draketo.de>
parents: 191
diff changeset
21 You can clone a Git repository from Hg by running `hg clone [url]`. For example, if you were to run `hg clone git://github.com/schacon/munger.git` it would clone the repository down into the directory 'munger.git', then convert it to an Hg repository for you.
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
22
327
f8a94616b957 README: prefix commands with dollar sign
Tay Ray Chuan <rctay89@gmail.com>
parents: 326
diff changeset
23 $ 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
24
200
dfed3bd84184 README: minor fixes
Abderrahim Kitouni <a.kitouni@gmail.com>
parents: 197
diff changeset
25 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
26
327
f8a94616b957 README: prefix commands with dollar sign
Tay Ray Chuan <rctay89@gmail.com>
parents: 326
diff changeset
27 $ 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
28 $ 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
29
192
03ef61d6882b Updated the readme some more...
Arne Babenhauserheide <bab@draketo.de>
parents: 191
diff changeset
30 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
31
327
f8a94616b957 README: prefix commands with dollar sign
Tay Ray Chuan <rctay89@gmail.com>
parents: 326
diff changeset
32 $ cd hg-git # (an Hg repository)
f8a94616b957 README: prefix commands with dollar sign
Tay Ray Chuan <rctay89@gmail.com>
parents: 326
diff changeset
33 $ # 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
34 $ hg push
197
11235deb86fc README: Added information about the git+ssh:// url format.
Arne Babenhauserheide <bab@draketo.de>
parents: 192
diff changeset
35
11235deb86fc README: Added information about the git+ssh:// url format.
Arne Babenhauserheide <bab@draketo.de>
parents: 192
diff changeset
36 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
37
191
c3aeeff8fb29 Updated the readme to include the usage of [paths].
Arne Babenhauserheide <bab@draketo.de>
parents: 163
diff changeset
38 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
39
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
40 $ hg pull
197
11235deb86fc README: Added information about the git+ssh:// url format.
Arne Babenhauserheide <bab@draketo.de>
parents: 192
diff changeset
41
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
42 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
43
319
3ab3765db5bc README.md: Improve Mercurial to Git conversion description.
Simon Ruderich <simon@ruderich.org>
parents: 318
diff changeset
44 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
45
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
46 $ 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
47 $ cd hg-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
48 $ hg bookmarks hg
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
49 $ 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
50
319
3ab3765db5bc README.md: Improve Mercurial to Git conversion description.
Simon Ruderich <simon@ruderich.org>
parents: 318
diff changeset
51 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
52
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
53 $ cd git-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
54 $ 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
55
319
3ab3765db5bc README.md: Improve Mercurial to Git conversion description.
Simon Ruderich <simon@ruderich.org>
parents: 318
diff changeset
56 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
57
f4a125201c5c README.md: Add information to convert Mercurial to Git.
Simon Ruderich <simon@ruderich.org>
parents: 255
diff changeset
58
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
59 Hg Bookmarks Integration
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
60 ========================
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
61
200
dfed3bd84184 README: minor fixes
Abderrahim Kitouni <a.kitouni@gmail.com>
parents: 197
diff changeset
62 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
63
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
64 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
65
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
66 Installing
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
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
69 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
70
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
71 [extensions]
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
72 hgext.bookmarks =
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
73 hggit = [path-to]/hg-git/hggit
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
74
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
75 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
76
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 43
diff changeset
77 Authors
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 43
diff changeset
78 ========
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 43
diff changeset
79
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 43
diff changeset
80 * 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
81 * 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
82 * 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
83 * 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
84 * 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
85
45
a4e53be79ca6 bit of doc cleanup - added dependencies section
Scott Chacon <schacon@gmail.com>
parents: 44
diff changeset
86 * 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
87
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 43
diff changeset
88 Sponsorship
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 43
diff changeset
89 ===========
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 43
diff changeset
90
45
a4e53be79ca6 bit of doc cleanup - added dependencies section
Scott Chacon <schacon@gmail.com>
parents: 44
diff changeset
91 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).