Mercurial > hg > hg-git

annotate DESIGN.txt @ 1006:31f52d62ae13

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
compat: add method for dulwich to return the symref
author Sean Farley <sean@farley.io>
date Fri, 15 May 2015 11:38:59 -0700
parents 1ec00e2805fb
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
1 Hg-Git Plugin Design Notes
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
2 ==========================
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
3
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
4 This plugin is designed to allow you to push to a Git server over the Git protocol and to pull from a Git based project. All data is stored in Hg native format with a mapping table. People collaborating in Git should not even be able to tell that you're using Hg to collaborate on their project (except for the '--HG--' section added to commit message).
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
5
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
6 Nothing should need to be kept in the Git format - you should be able to run 'hg gclear' at any time to wipe out the Git directory and everything can be rebuilt losslessly from the existing Hg data - it is a cache only.
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
7
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
8 We are using the Dulwich library, which I've modified quite a bit - I'll have to get these changes back upstream at some point.
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
9
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
10 I've been adding 'TODO' comments all over the place where I only partially implemented something so I could get the entire first draft of functionality completed. The TODO areas should be mostly edge cases (executable bits, file rename info, tags, submodules, etc).
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
11
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
12 Lossless Two Way
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
13 ================
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
14
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
15 We need to store data that Git records that Merc does not in a git/extra_data file. This would be parents over two and committer information (author will be mapped to Hg committer). This way two Hg developers can collaborate without the Git transport messing up the local commits.
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
16
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
17 Each Git commit should be reproducible as a Merc ID and vice versa on any system without losing data (ie changing the SHA).
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
18
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
19 Branch Translation Policy
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
20 =========================
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
21
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
22 Branches in Hg and Git are pretty different. This is meant to provide a clear policy on how one is converted to the other.
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
23
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
24 * Without Bookmarks: *
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
25
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
26 If you don't have bookmarks enabled, Git simply maps your 'tip' to the 'master' branch of the repository you're pushing to, since that is the most commonly used default branch name. Actually, pulling will map whatever the server points to as HEAD, but when pushing it will assume 'master' is your tip.
5
d6c443a91b18 refactored the git handling stuff out into another class
Scott Chacon <schacon@gmail.com>
parents: 2
diff changeset
27
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
28 $ hg gpush origin # will push tip to remote 'master'
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
29 $ hg gpush origin master # same as above
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
30 $ hg gpush origin --all # same as above
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
31
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
32 If the remote server has divergent branches (branches with commits not reachable from HEAD) it will basically ignore them, not convert them into Hg changesets. It will tell you this (and why) when fetched.
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
33
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
34 Conversely, on pushing, Hg named branches are ignored if they are not reachable from traversing the parents of tip. (SC: is this best?)
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
35
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
36 * With Bookmarks: *
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
37
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
38 If you have bookmarks enabled, it will treat your bookmarks like Git branches and will only push up references if you specify them.
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
39
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
40 hg gpush origin # will error, you have to specify a branch
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
41 hg gpush origin master # pushes the master branch
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
42 hg gpush origin --all # pushes all local branches
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
43
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
44 If a fetch gets branches, it _will_ import them and will create bookmarks that point to them, even if they have no common ancestors with the mainline (HEAD).
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
45
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
46 * Other points *
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
47
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
48 If you do not specify a remote name, it will assume 'origin'. This is helpful if you do not have bookmarks enabled as it will push tip automatically. If you have bookmarks enabled this is not helpful because you have to specify a branch name after.
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
49
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
50 Eventually, I would like to setup tracking branch refspecs much like Git - say 'this local branch pushes and pulls to/from this remote and branch', but that will be one of the last things done.
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
51
44
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
52 Testing Hg-Git
234bb5784c8b cleaned up documentation, created initial branch policy
Scott Chacon <schacon@gmail.com>
parents: 18
diff changeset
53 ==============
2
c43c02cc803a added dulwich library and got the script to call it for clone
Scott Chacon <schacon@gmail.com>
parents:
diff changeset
54
18
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
55 Tests are implemented in the Mercurial-standard way of small shell scripts.
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
56 The scripts are located in the tests directory, and to run them you should
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
57 change to that directory and then run tests/run-tests.py from the Mercurial
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
58 sources. For example, if you have a copy of the Mercurial source code at
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
59 /Stuff/hg-crew, you would do something like this:
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
60
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
61 cd tests ; /Stuff/hg-crew/tests/run-tests.py
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
62
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
63 And you should see output like this:
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
64 .
feab56c76c92 Add a basic test for cloning.
Augie Fackler <durin42@gmail.com>
parents: 5
diff changeset
65 # Ran 1 tests, 0 skipped, 0 failed.