Mercurial > hg-git

annotate README.md @ 450:163ac98569d3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
- add "author file" extension, allows an author translation map to put more legit author names in the outgoing git repo
author Mike Bayer <mike_mp@zzzcomputing.com>
date Thu, 23 Feb 2012 13:49:07 -0500
parents 2e8820592bd3
children a2446c8cf005
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
1 Hg-Git Mercurial Plugin
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
2 =======================
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
3
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
4 This is the Hg-Git plugin for Mercurial, adding the ability to push
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
5 and pull to/from a Git server repository from Hg. This means you can
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
6 collaborate on Git based projects from Hg, or use a Git server as a
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
7 collaboration point for a team with developers using both Git and Hg.
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
8
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
9 The Hg-Git plugin can convert commits/changesets losslessly from one
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
10 system to another, so you can push via an Hg repository and another Hg
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
11 client can pull it and their changeset node ids will be identical -
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
12 Mercurial data does not get lost in translation. It is intended that
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
13 Hg users may wish to use this to collaborate even if no Git users are
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
14 involved in the project, and it may even provide some advantages if
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
15 you're using Bookmarks (see below).
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
16
45
a4e53be79ca6 bit of doc cleanup - added dependencies section
Scott Chacon <schacon@gmail.com>
parents: 44
diff changeset
17 Dependencies
a4e53be79ca6 bit of doc cleanup - added dependencies section
Scott Chacon <schacon@gmail.com>
parents: 44
diff changeset
18 ============
a4e53be79ca6 bit of doc cleanup - added dependencies section
Scott Chacon <schacon@gmail.com>
parents: 44
diff changeset
19
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
20 This plugin is implemented entirely in Python - there are no Git
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
21 binary dependencies, you do not need to have Git installed on your
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
22 system. The only dependencies are Mercurial and Dulwich. The plugin
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
23 is known to work on Hg versions 1.3 through 1.5 and requires at least
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
24 Dulwich 0.6.0.
45
a4e53be79ca6 bit of doc cleanup - added dependencies section
Scott Chacon <schacon@gmail.com>
parents: 44
diff changeset
25
331
c3ecdfcb91e7 README: rename 'Commands' section to 'Usage'
Tay Ray Chuan <rctay89@gmail.com>
parents: 330
diff changeset
26 Usage
c3ecdfcb91e7 README: rename 'Commands' section to 'Usage'
Tay Ray Chuan <rctay89@gmail.com>
parents: 330
diff changeset
27 =====
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
28
328
5875262c92ac README: reword clone command section
Tay Ray Chuan <rctay89@gmail.com>
parents: 327
diff changeset
29 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
30 example, if you were to run
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 $ 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
33
328
5875262c92ac README: reword clone command section
Tay Ray Chuan <rctay89@gmail.com>
parents: 327
diff changeset
34 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
35 convert it to an Hg repository for you.
5875262c92ac README: reword clone command section
Tay Ray Chuan <rctay89@gmail.com>
parents: 327
diff changeset
36
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
37 If you want to clone a github repository for later pushing (or any
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
38 other repository you access via ssh), you need to convert the ssh url
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
39 to a format with an explicit protocol prefix. For example, the git url
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
40 with push access
330
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
41
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
42 git@github.com:schacon/hg-git.git
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
43
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
44 would read
200
dfed3bd84184 README: minor fixes
Abderrahim Kitouni <a.kitouni@gmail.com>
parents: 197
diff changeset
45
330
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
46 git+ssh://git@github.com/schacon/hg-git.git
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
47
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
48 (Mind the switch from colon to slash after the host!)
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
49
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
50 Your clone command would thus look like this:
37ff4189b05b README: make url conversion more explicit
Tay Ray Chuan <rctay89@gmail.com>
parents: 329
diff changeset
51
327
f8a94616b957 README: prefix commands with dollar sign
Tay Ray Chuan <rctay89@gmail.com>
parents: 326
diff changeset
52 $ 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
53
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
54 If you are starting from an existing Hg repository, you have to setup
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
55 a Git repository somewhere that you have push access to, add it as
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
56 default path or default-push path in your .hg/hgrc and then run `hg
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
57 push` from within your project. For example:
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
58
327
f8a94616b957 README: prefix commands with dollar sign
Tay Ray Chuan <rctay89@gmail.com>
parents: 326
diff changeset
59 $ cd hg-git # (an Hg repository)
f8a94616b957 README: prefix commands with dollar sign
Tay Ray Chuan <rctay89@gmail.com>
parents: 326
diff changeset
60 $ # 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
61 $ hg push
197
11235deb86fc README: Added information about the git+ssh:// url format.
Arne Babenhauserheide <bab@draketo.de>
parents: 192
diff changeset
62
11235deb86fc README: Added information about the git+ssh:// url format.
Arne Babenhauserheide <bab@draketo.de>
parents: 192
diff changeset
63 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
64
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
65 Now that you have an Hg repository that can push/pull to/from a Git
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
66 repository, you can fetch updates with `hg pull`.
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
67
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
68 $ hg pull
197
11235deb86fc README: Added information about the git+ssh:// url format.
Arne Babenhauserheide <bab@draketo.de>
parents: 192
diff changeset
69
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
70 That will pull down any commits that have been pushed to the server in
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
71 the meantime and give you a new head that you can merge in.
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
72
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
73 Hg-Git can also be used to convert a Mercurial repository to Git. As
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
74 Dulwich doesn't support local repositories yet, the easiest way is to
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
75 setup up a local SSH server. Then use the following commands to
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
76 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
77
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
78 $ 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
79 $ cd hg-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
80 $ hg bookmarks hg
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
81 $ 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
82
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
83 The hg bookmark is necessary to prevent problems as otherwise hg-git
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
84 pushes to the currently checked out branch confusing Git. This will
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
85 create a branch named hg in the Git repository. To get the changes in
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
86 master use the following command (only necessary in the first run,
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
87 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
88
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
89 $ cd git-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
90 $ 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
91
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
92 To import new changesets into the Git repository just rerun the hg
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
93 push command and then use git merge or git rebase in your Git
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
94 repository.
318
f4a125201c5c README.md: Add information to convert Mercurial to Git.
Simon Ruderich <simon@ruderich.org>
parents: 255
diff changeset
95
332
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
96 Commands
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
97 ========
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
98
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
99 gclear
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
100 ------
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
101
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
102 TODO
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
103
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
104 gimport
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
105 -------
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
106
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
107 TODO
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
108
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
109 gexport
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
110 -------
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
111
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
112 TODO
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
113
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
114 git-cleanup
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
115 -----------
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
116
9d9a55b0a8af README: add 'Commands' section and stubs
Tay Ray Chuan <rctay89@gmail.com>
parents: 331
diff changeset
117 TODO
318
f4a125201c5c README.md: Add information to convert Mercurial to Git.
Simon Ruderich <simon@ruderich.org>
parents: 255
diff changeset
118
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
119 Hg Bookmarks Integration
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
120 ========================
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
121
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
122 If you have the bookmarks extension enabled, Hg-Git will use it. It
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
123 will push your bookmarks up to the Git server as branches and will
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
124 pull Git branches down and set them up as bookmarks.
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
125
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
126 Installing
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
127 ==========
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
128
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
129 Clone this repository somewhere and make the 'extensions' section in
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
130 your `~/.hgrc` file look something like this:
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
131
326
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
132 [extensions]
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
133 hgext.bookmarks =
62315903f88b README: use bare-minimum of 4 spaces for code blocks
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
134 hggit = [path-to]/hg-git/hggit
43
e965895856e9 initial readme file
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
135
341
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
136 That will enable the Hg-Git extension for you. The bookmarks section
1f9f4ff47618 README: 80 columns cleanup.
Augie Fackler <durin42@gmail.com>
parents: 340
diff changeset
137 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
138
325
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
139 Configuration
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
140 =============
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
141
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
142 git.intree
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
143 ----------
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
144
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
145 hg-git keeps a git repository clone for reading and updating. By default, the
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
146 git clone is the subdirectory `git` in your local Mercurial repository. If you
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
147 would like this git clone to be at the same level of your Mercurial repository
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
148 instead (named `.git`), add the following to your `hgrc`:
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
149
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
150 [git]
ef7a7df7a8a7 README: document git.intree
Tay Ray Chuan <rctay89@gmail.com>
parents: 319
diff changeset
151 intree = True
449
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
152
450
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
153 git.authors
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
154 -----------
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
155
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
156 Git uses a strict convention for "author names" when representing changesets,
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
157 using the form `[realname] [email address]`. Mercurial encourages this
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
158 convention as well but is not as strict, so it's not uncommon for a Mercurial
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
159 repo to have authors listed as simple usernames. hg-git by default will
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
160 translate such names using the email address `none@none`, which then shows up
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
161 unpleasantly on GitHub as "illegal email address".
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
162
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
163 The `git.authors` option provides for an "authors translation file" that will
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
164 be used during outgoing transfers from mercurial to git only, by modifying
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
165 `hgrc` as such:
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
166
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
167 [git]
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
168 authors = authors.txt
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
169
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
170 Where `authors.txt` is the name of a text file containing author name translations,
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
171 one per each line, using the following format:
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
172
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
173 johnny = John Smith <jsmith@foo.com>
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
174 dougie = Doug Johnson <dougiej@bar.com>
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
175
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
176 Empty lines and lines starting with a "#" are ignored.
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
177
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
178 It should be noted that **this translation is on the hg->git side only**. Changesets
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
179 coming from Git back to Mercurial will not translate back into hg usernames, so
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
180 it's best that the same username/email combination be used on both the hg and git sides;
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
181 the author file is mostly useful for translating legacy changesets.
163ac98569d3 - add "author file" extension, allows an author translation map
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 449
diff changeset
182
449
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
183 git.branch_bookmark_suffix
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
184 ---------------------------
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
185
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
186 hg-git does not convert between Mercurial named branches and git branches as
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
187 the two are conceptually different; instead, it uses Mercurial bookmarks to
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
188 represent the concept of a git branch. Therefore, when translating an hg repo
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
189 over to git, you typically need to create bookmarks to mirror all the named
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
190 branches that you'd like to see transferred over to git. The major caveat with
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
191 this is that you can't use the same name for your bookmark as that of the
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
192 named branch, and furthermore there's no feasible way to rename a branch in
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
193 Mercurial. For the use case where one would like to transfer an hg repo over
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
194 to git, and maintain the same named branches as are present on the hg side,
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
195 the `branch_bookmark_suffix` might be all that's needed. This presents a
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
196 string "suffix" that will be recognized on each bookmark name, and stripped
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
197 off as the bookmark is translated to a git branch:
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
198
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
199 [git]
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
200 branch_bookmark_suffix=_bookmark
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
201
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
202 Above, if an hg repo had a named branch called `release_6_maintenance`, you could
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
203 then link it to a bookmark called `release_6_maintenance_bookmark`. hg-git will then
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
204 strip off the `_bookmark` suffix from this bookmark name, and create a git branch
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
205 called `release_6_maintenance`. When pulling back from git to hg, the `_bookmark`
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
206 suffix is then applied back, if and only if an hg named branch of that name exists.
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
207 E.g., when changes to the `release_6_maintenance` branch are checked into git, these
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
208 will be placed into the `release_6_maintenance_bookmark` bookmark on hg. But if a
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
209 new branch called `release_7_maintenance` were pulled over to hg, and there was
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
210 not a `release_7_maintenance` named branch already, the bookmark will be named
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
211 `release_7_maintenance` with no usage of the suffix.
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
212
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
213 The `branch_bookmark_suffix` option is, like the `authors` option, intended for
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
214 migrating legacy hg named branches. Going forward, an hg repo that is to
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter
Mike Bayer <mike_mp@zzzcomputing.com>
parents: 440
diff changeset
215 be linked with a git repo should only use bookmarks for named branching.