hg-git: README.md annotate

annotate README.md @ 1092:3799bf885c1d

compat: use newer read_pkt_refs from dulwich if possible Beginning with dulwich 0.18, it now supports reporting the symrefs so we no longer need to monkey patch (will require future patches to use the new code, though).

author	Sean Farley <sean@farley.io>
date	Mon, 27 Nov 2017 17:45:51 -0500
parents	3b20ecf51ed5
children

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
459 a2446c8cf005 README: add URLs of homepage, primary hg repo, and git mirror repo Brian Warner <warner@lothar.com> parents: 450 diff changeset	4 * Homepage: http://hg-git.github.com/
a2446c8cf005 README: add URLs of homepage, primary hg repo, and git mirror repo Brian Warner <warner@lothar.com> parents: 450 diff changeset	5 * https://bitbucket.org/durin42/hg-git (primary)
a2446c8cf005 README: add URLs of homepage, primary hg repo, and git mirror repo Brian Warner <warner@lothar.com> parents: 450 diff changeset	6 * https://github.com/schacon/hg-git (mirror)
a2446c8cf005 README: add URLs of homepage, primary hg repo, and git mirror repo Brian Warner <warner@lothar.com> parents: 450 diff changeset	7
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	8 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	9 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	10 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	11 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	12
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	13 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	14 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	15 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	16 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	17 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	18 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	19 you're using Bookmarks (see below).
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	20
45 a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	21 Dependencies
a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	22 ============
a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	23
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	24 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	25 binary dependencies, you do not need to have Git installed on your
724 91b621c6ba9a readme: drop Mercurial and Dulwich compatibilty information Siddharth Agarwal <sid0@fb.com> parents: 674 diff changeset	26 system. The only dependencies are Mercurial and Dulwich. See the
91b621c6ba9a readme: drop Mercurial and Dulwich compatibilty information Siddharth Agarwal <sid0@fb.com> parents: 674 diff changeset	27 Makefile for information about which versions of Mercurial are
91b621c6ba9a readme: drop Mercurial and Dulwich compatibilty information Siddharth Agarwal <sid0@fb.com> parents: 674 diff changeset	28 known to work, and setup.py for which versions of Dulwich are required.
45 a4e53be79ca6 bit of doc cleanup - added dependencies section Scott Chacon <schacon@gmail.com> parents: 44 diff changeset	29
331 c3ecdfcb91e7 README: rename 'Commands' section to 'Usage' Tay Ray Chuan <rctay89@gmail.com> parents: 330 diff changeset	30 Usage
c3ecdfcb91e7 README: rename 'Commands' section to 'Usage' Tay Ray Chuan <rctay89@gmail.com> parents: 330 diff changeset	31 =====
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	32
481 9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	33 You can clone a Git repository from Hg by running `hg clone <url> [dest]`. For
328 5875262c92ac README: reword clone command section Tay Ray Chuan <rctay89@gmail.com> parents: 327 diff changeset	34 example, if you were to run
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 $ 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	37
481 9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	38 Hg-Git would clone the repository and convert it to an Hg repository
9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	39 for you.
328 5875262c92ac README: reword clone command section Tay Ray Chuan <rctay89@gmail.com> parents: 327 diff changeset	40
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	41 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	42 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	43 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	44 with push access
330 37ff4189b05b README: make url conversion more explicit Tay Ray Chuan <rctay89@gmail.com> parents: 329 diff changeset	45
37ff4189b05b README: make url conversion more explicit Tay Ray Chuan <rctay89@gmail.com> parents: 329 diff changeset	46 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 would read
200 dfed3bd84184 README: minor fixes Abderrahim Kitouni <a.kitouni@gmail.com> parents: 197 diff changeset	49
330 37ff4189b05b README: make url conversion more explicit Tay Ray Chuan <rctay89@gmail.com> parents: 329 diff changeset	50 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	51
37ff4189b05b README: make url conversion more explicit Tay Ray Chuan <rctay89@gmail.com> parents: 329 diff changeset	52 (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	53
37ff4189b05b README: make url conversion more explicit Tay Ray Chuan <rctay89@gmail.com> parents: 329 diff changeset	54 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	55
327 f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	56 $ 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	57
481 9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	58 If you are starting from an existing Hg repository, you have to set up
9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	59 a Git repository somewhere that you have push access to, add a path entry
9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	60 for it in your .hg/hgrc file, and then run `hg push [name]` from within
9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	61 your repository. For example:
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	62
327 f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	63 $ cd hg-git # (an Hg repository)
f8a94616b957 README: prefix commands with dollar sign Tay Ray Chuan <rctay89@gmail.com> parents: 326 diff changeset	64 $ # 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	65 $ hg push
197 11235deb86fc README: Added information about the git+ssh:// url format. Arne Babenhauserheide <bab@draketo.de> parents: 192 diff changeset	66
481 9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	67 This will convert all your Hg data into Git objects and push them to the Git server.
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	68
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	69 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	70 repository, you can fetch updates with `hg pull`.
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	71
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	72 $ hg pull
197 11235deb86fc README: Added information about the git+ssh:// url format. Arne Babenhauserheide <bab@draketo.de> parents: 192 diff changeset	73
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	74 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	75 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	76
530 1ec00e2805fb docs: update to correctly reflect that local git repositories are supported David M. Carr <david@carrclan.us> parents: 526 diff changeset	77 Hg-Git can also be used to convert a Mercurial repository to Git. You can use
1ec00e2805fb docs: update to correctly reflect that local git repositories are supported David M. Carr <david@carrclan.us> parents: 526 diff changeset	78 a local repository or a remote repository accessed via SSH, HTTP or HTTPS. Use
728 2f8bedc6007d Fixed small typo CoolOppo <CoolOppo@users.noreply.github.com> parents: 724 diff changeset	79 the following commands to convert the repository (it assumes you're running this
530 1ec00e2805fb docs: update to correctly reflect that local git repositories are supported David M. Carr <david@carrclan.us> parents: 526 diff changeset	80 in $HOME).
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	81
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	82 $ 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	83 $ cd hg-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	84 $ hg bookmarks hg
530 1ec00e2805fb docs: update to correctly reflect that local git repositories are supported David M. Carr <david@carrclan.us> parents: 526 diff changeset	85 $ hg push ../git-repo
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	86
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	87 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	88 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	89 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	90 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	91 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	92
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	93 $ cd git-repo
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	94 $ 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	95
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	96 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	97 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	98 repository.
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	99
332 9d9a55b0a8af README: add 'Commands' section and stubs Tay Ray Chuan <rctay89@gmail.com> parents: 331 diff changeset	100 Commands
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
1081 42df62660ac8 doc: clean up README and TODO Kevin Bullock <kbullock@ringworld.org> parents: 950 diff changeset	103 See `hg help -e hggit`.
318 f4a125201c5c README.md: Add information to convert Mercurial to Git. Simon Ruderich <simon@ruderich.org> parents: 255 diff changeset	104
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	105 Hg Bookmarks Integration
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	106 ========================
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	107
526 8ede232d3c70 readme: remove references to bookmarks being optional David M. Carr <david@carrclan.us> parents: 522 diff changeset	108 Hg-Git pushes your bookmarks up to the Git server as branches and will
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	109 pull Git branches down and set them up as bookmarks.
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	110
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	111 Installing
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	112 ==========
e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	113
341 1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	114 Clone this repository somewhere and make the 'extensions' section in
1f9f4ff47618 README: 80 columns cleanup. Augie Fackler <durin42@gmail.com> parents: 340 diff changeset	115 your `~/.hgrc` file look something like this:
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	116
326 62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	117 [extensions]
62315903f88b README: use bare-minimum of 4 spaces for code blocks Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	118 hggit = [path-to]/hg-git/hggit
43 e965895856e9 initial readme file Scott Chacon <schacon@gmail.com> parents: diff changeset	119
526 8ede232d3c70 readme: remove references to bookmarks being optional David M. Carr <david@carrclan.us> parents: 522 diff changeset	120 That will enable the Hg-Git extension for you.
44 234bb5784c8b cleaned up documentation, created initial branch policy Scott Chacon <schacon@gmail.com> parents: 43 diff changeset	121
945 93d70993447c readme: remove compatibility list Siddharth Agarwal <sid0@fb.com> parents: 846 diff changeset	122 See the Makefile for a list of compatible Mercurial versions.
481 9df1741f3977 help: add additional help topics David M. Carr <david@carrclan.us> parents: 459 diff changeset	123
325 ef7a7df7a8a7 README: document git.intree Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	124 Configuration
ef7a7df7a8a7 README: document git.intree Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	125 =============
ef7a7df7a8a7 README: document git.intree Tay Ray Chuan <rctay89@gmail.com> parents: 319 diff changeset	126
450 163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	127 git.authors
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	128 -----------
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	129
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	130 Git uses a strict convention for "author names" when representing changesets,
950 c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	131 using the form `[realname] [email address]`. Mercurial encourages this
450 163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	132 convention as well but is not as strict, so it's not uncommon for a Mercurial
950 c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	133 repo to have authors listed as, for example, simple usernames. hg-git by default
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	134 will attempt to translate Mercurial usernames using the following rules:
450 163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	135
950 c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	136 * If the Mercurial username fits the pattern `NAME <EMAIL>`, the git name will be
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	137 set to NAME and the email to EMAIL.
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	138 * If the Mercurial username looks like an email (if it contains an `@`), the
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	139 git name and email will both be set to that email.
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	140 * If the Mercurial username consists of only a name, the email will be set to `none@none`.
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	141 * Illegal characters (stray `<`s or `>`s) will be stripped out, and for `NAME <EMAIL>`
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	142 usernames, any content after the right-bracket (for example, a second `>`) will be
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	143 turned into a url-encoded sigil like `ext:(%3E)` in the git author name.
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	144
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	145 Since these default behaviors may not be what you want (`none@none`, for example,
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	146 shows up unpleasantly on Github as "illegal email address"), the `git.authors`
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	147 option provides for an "authors translation file" that will be used during outgoing
c705bd4236f4 readme: document the specific behaviors of hg author translation mcc <andi.m.mcclure@gmail.com> parents: 945 diff changeset	148 transfers from mercurial to git only, by modifying `hgrc` as such:
450 163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	149
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	150 [git]
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	151 authors = authors.txt
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	152
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	153 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	154 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	155
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	156 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	157 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	158
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	159 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	160
163ac98569d3 - add "author file" extension, allows an author translation map Mike Bayer <mike_mp@zzzcomputing.com> parents: 449 diff changeset	161 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	162 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	163 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	164 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	165
1087 3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	166 git.blockdotgit
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	167 ---------------
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	168
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	169 Blocks exporting revisions to Git that contain a directory named .git or any
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	170 letter-case variation thereof. This prevents creating repositories that newer
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	171 versions of Git and many Git hosting services block due to security
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	172 concerns. Defaults to True.
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	173
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	174 git.blockdothg
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	175 --------------
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	176
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	177 Blocks importing revisions from Git that contain a directory named .hg. Defaults
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	178 to True.
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	179
449 2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	180 git.branch_bookmark_suffix
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	181 ---------------------------
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	182
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	183 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	184 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	185 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	186 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	187 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	188 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	189 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	190 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	191 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	192 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	193 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	194 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	195
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	196 [git]
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	197 branch_bookmark_suffix=_bookmark
1086 c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	198
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	199 Above, if an hg repo had a named branch called `release_6_maintenance`, you could
449 2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	200 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	201 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	202 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	203 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	204 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	205 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	206 new branch called `release_7_maintenance` were pulled over to hg, and there was
1086 c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	207 not a `release_7_maintenance` named branch already, the bookmark will be named
449 2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	208 `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	209
2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	210 The `branch_bookmark_suffix` option is, like the `authors` option, intended for
1086 c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	211 migrating legacy hg named branches. Going forward, an hg repo that is to
449 2e8820592bd3 Add documentation for branch_bookmark_suffix configuration parameter Mike Bayer <mike_mp@zzzcomputing.com> parents: 440 diff changeset	212 be linked with a git repo should only use bookmarks for named branching.
824 27ac3cb46c9d readme: add docs for git.mindate Siddharth Agarwal <sid0@fb.com> parents: 728 diff changeset	213
1086 c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	214 git.findcopiesharder
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	215 --------------------
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	216
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	217 Whether to consider unmodified files as copy sources. This is a very expensive
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	218 operation for large projects, so use it with caution. Similar to `git diff`'s
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	219 --find-copies-harder option.
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	220
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	221 git.intree
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	222 ----------
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	223
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	224 hg-git keeps a git repository clone for reading and updating. By default, the
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	225 git clone is the subdirectory `git` in your local Mercurial repository. If you
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	226 would like this git clone to be at the same level of your Mercurial repository
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	227 instead (named `.git`), add the following to your `hgrc`:
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	228
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	229 [git]
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	230 intree = True
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	231
824 27ac3cb46c9d readme: add docs for git.mindate Siddharth Agarwal <sid0@fb.com> parents: 728 diff changeset	232 git.mindate
27ac3cb46c9d readme: add docs for git.mindate Siddharth Agarwal <sid0@fb.com> parents: 728 diff changeset	233 -----------
27ac3cb46c9d readme: add docs for git.mindate Siddharth Agarwal <sid0@fb.com> parents: 728 diff changeset	234
27ac3cb46c9d readme: add docs for git.mindate Siddharth Agarwal <sid0@fb.com> parents: 728 diff changeset	235 If set, branches where the latest commit's commit time is older than this will
27ac3cb46c9d readme: add docs for git.mindate Siddharth Agarwal <sid0@fb.com> parents: 728 diff changeset	236 not be imported. Accepts any date formats that Mercurial does -- see
27ac3cb46c9d readme: add docs for git.mindate Siddharth Agarwal <sid0@fb.com> parents: 728 diff changeset	237 `hg help dates` for more.
846 82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	238
1087 3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	239 git.public
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	240 ----------
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	241
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	242 A list of Git branches that should be considered "published", and therefore
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	243 converted to Mercurial in the 'public' phase. This is only used if
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	244 hggit.usephases is set.
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	245
846 82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	246 git.renamelimit
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	247 ---------------
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	248
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	249 The number of files to consider when performing the copy/rename detection.
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	250 Detection is disabled if the number of files modified in a commit is above the
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	251 limit. Detection is O(N^2) in the number of files modified, so be sure not to
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	252 set the limit too high. Similar to Git's `diff.renameLimit` config. The default
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	253 is "400", the same as Git.
82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	254
1086 c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	255 git.similarity
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	256 --------------
846 82b457515ddb readme: add docs for rename detection options Siddharth Agarwal <sid0@fb.com> parents: 824 diff changeset	257
1086 c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	258 Specify how similar files modified in a Git commit must be to be imported as
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	259 Mercurial renames or copies, as a percentage between "0" (disabled) and "100"
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	260 (files must be identical). For example, "90" means that a delete/add pair will
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	261 be imported as a rename if more than 90% of the file has stayed the same. The
c71dc6e5c62a doc: sort config options in alphabetical order Kevin Bullock <kbullock@ringworld.org> parents: 1081 diff changeset	262 default is "0" (disabled).
1087 3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	263
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	264 hggit.mapsavefrequency
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	265 ----------------------
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	266
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	267 Controls how often the mapping between Git and Mercurial commit hashes gets
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	268 saved when importing or exporting changesets. Set this to a number greater than
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	269 0 to save the mapping after converting that many commits. This can help when the
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	270 conversion encounters an error partway through a large batch of
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	271 changes. Defaults to 0, so that the mapping is saved once at the end.
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	272
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	273 hggit.usephases
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	274 ---------------
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	275
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	276 When converting Git revisions to Mercurial, place them in the 'public' phase as
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	277 appropriate. Namely, revisions that are reachable from the remote Git
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	278 repository's HEAD will be marked 'public'. For most repositories, this means the
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	279 remote 'master' will be converted as public. This speeds up some local Mercurial
3b20ecf51ed5 doc: document all config options in README Kevin Bullock <kbullock@ringworld.org> parents: 1086 diff changeset	280 operations including `hg shelve`.

Mercurial > hg-git

annotate README.md @ 1092:3799bf885c1d