Mercurial > hgsubversion

comparison hgsubversion/help/subversion.rst @ 659:55d6697b975a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
help: add an rst file containing some helpful instructions The new file contains three sections: The first one is based on the README and contains instructions on how to use hgsubversion. The second one mentions the most notable shortcomings of hgsubversion. The third and final section documents how to customise hgsubversion.
author Dan Villiom Podlaski Christiansen <danchr@gmail.com>
date Wed, 11 Aug 2010 19:57:34 +0200
parents
children 703f33576ad8
comparison
equal deleted inserted replaced
658:d101b39f6c51 659:55d6697b975a
1 Basic Use
2 ---------
3
4 Converting a Subversion repository to Mercurial with hgsubversion is done by
5 cloning it. Subversion repositories are specified using the same, regular URL
6 syntax as Subversion uses. hgsubversion accepts URIs such as the following:
7
8 - http://user:sekrit@example.com/repo
9 - https://user@example.com/repo
10 - svn://example.com/repo
11 - svn+ssh://example.com/repo
12 - file:///tmp/repo
13
14 In the case of the two first schemas, HTTP and HTTPS, the repository is first
15 treated as a Mercurial repository, and a Subversion pull attempted should it
16 fail. As this can be particularly annoying for repositories that require
17 authentication, such repositories may also specified using a svn+http or
18 svn+https schema.
19
20 To create a new Mercurial clone, you can use a command such as the following::
21
22 $ hg clone <repository URI> [destination]
23
24 Or with a real example::
25
26 $ hg clone http://python-nose.googlecode.com/svn nose-hg
27
28 Please note that there are two slightly different ways of cloning repositories:
29
30 The most common desire is to have the full history of a repository, including
31 all its tags and branches. In such cases you should clone from one level above
32 trunk, as in the example above. This is known as `standard layout`, and works
33 with repositories that use the conventional `trunk`, `tags` and `branches`
34 directories. By default, hgsubversion will use this layout whenever it finds any
35 of these directories at the specified directory on the server.
36
37 If you instead want to clone just a single directory or branch, clone the
38 specific directory path. In the example above, to get *only* trunk, you would
39 issue :hg:`clone http://python-nose.googlecode.com/svn/trunk nose-trunk`. This
40 works with any directory with a Subversion repository, and is know as a single
41 directory clone.
42
43 Pulling new revisions into an already-converted repo is the same as from any
44 other Mercurial source. Within the first example above, the following three
45 commands are all equivalent::
46
47 $ hg pull
48 $ hg pull default
49 $ hg pull http://python-nose.googlecode.com/svn
50
51 Sometimes, past repository history is of little or no interest, and all that is
52 wanted is access to current and future history from Mercurial. The --startrev
53 option with the HEAD argument causes the initial clone to only convert the
54 latest revision; later pulls will convert all revisions following the first.
55 Please note that this only works for single-directory clones.
56
57 Support for externals
58 -----------------------------
59
60 All ``svn:externals`` properties are serialized into a single
61 ``.hgsvnexternals`` file having the following syntax::
62
63 [.]
64 common1 http://path/to/external/svn/repo1
65 ...additional svn:externals properties lines...
66 [dir2]
67 common2 -r123 http://path/to/external/svn/repo2
68 ...additional svn:externals properties lines...
69
70 A header line in brackets specifies the directory the property applies
71 to, where '.' indicates the project root directory. The property content
72 follows the header, with every content line being prefixed by a single
73 space. Note that the property lines have a format identical to
74 svn:externals properties as used in Subversion, and do not support the
75 hgsubversion extended svn+http:// URL format.
76
77 Issuing the command :hg:`svn updateexternals` with the ``.hgsvnexternals``
78 example above would fetch the latest revision of repo1 into the subdirectory
79 *./common1*, and revision 123 of repo2 into *dir2/common2*. Note that
80 ``.hgsvnexternals`` must be tracked by Mercurial before this will work. If
81 ``.hgsvnexternals`` is created or changed, it
82 will not be pushed to the related Subversion repository, but its
83 contents **will** be used to update ``svn:externals`` properties on the
84 related Subversion repository.
85
86 Limitations
87 -----------
88
89 Currently, pushing to Subversion destroys the original changesets and replaces
90 them with new ones converted from the resulting commits. Due to the intricacies
91 of Subversion semantics, these converted changesets may differ in subtle ways
92 from the original Mercurial changests. For example, the commit date almost
93 always changes. This makes hgsubversion unsuitable for use as a two-way bridge.
94
95 When converting from Subversion, hgsubversion does not recognize merge-info, and
96 does not create merges based on it. Similarly, Mercurial merges cannot be pushed
97 to Subversion.
98
99 Changesets that create tags cannot be pushed to Subversion, as support for
100 creating Subversion tags has not been implemented, yet.
101
102 Standard layout does not work with repositories that use unconventional
103 layouts. Thus, only a single directory clones can be made of such repositories.
104
105 When interacting with Subversion, hgsubversion relies on information about the
106 previously converted changesets. This information will not be updated if pushing
107 or pulling converted changesets to or from any other source. To regenerate the
108 stored metadata, run :hg:`svn rebuildmeta [URI]`. This must also be done if any
109 converted changesets are ever removed from the repository.
110
111 It is not possible to interact with more than one Subversion repository per
112 Mercurial clone. Please note that this also applies to more than one path within
113 a repository.
114
115 Advanced Configuration
116 ----------------------
117
118 The operation of hgsubversion can be customized by the following configuration
119 settings:
120
121 hgsubversion.authormap
122 Path to a file for mapping usernames from Subversion to Mercurial. For
123 example::
124
125 joe = Joe User <joe@example.com>
126
127 hgsubversion.defaulthost
128 This option specifies the hostname to append to unmapped Subversion
129 usernames. The default is to append the UUID of the Subversion repository
130 as a hostname. That is, an author of `bob` may be mapped to
131 `bob@0b1d8996-7ded-4192-9199-38e2bec458fb`.
132
133 If this option set to an empty string, the Subversion authors will be used
134 with no hostname component.
135
136 hgsubversion.defaultauthors
137 Setting this boolean option to true will cause hgsubversion to abort a
138 conversion if a revision has an author not listed in the author map.
139
140 hgsubversion.branchmap
141 Path to a file for changing branch names during the conversion from
142 Subversion to Mercurial.
143
144 hgsubversion.filemap
145 Path to a file for filtering files during the conversion. Files may either
146 be excluded or included. See the documentation for :hg:`convert` for more
147 information on filemaps.
148
149 hgsubversion.username, hgsubversion.password
150 Set the username or password for accessing Subversion repositories.
151
152 hgsubversion.stupid
153 Setting this boolean option to true will force using a slower method for
154 pulling revisions from Subversion. This method is compatible with servers
155 using very old versions of Subversion, and hgsubversion falls back to it
156 when necessary.
157
158 The following options only have an effect on the initial clone of a repository:
159
160 hgsubversion.layout
161 Set the layout of the repository. `standard` assumes a normal
162 trunk/branches/tags layout. `single` means that the entire repository is
163 converted into a single branch. The default, `auto`, causes hgsubversion to
164 assume a standard layout if any of trunk, branches, or tags exist within the
165 specified directory on the server.
166
167 hgsubversion.startrev
168 Convert Subversion revisions starting at the one specified, either an
169 integer revision or HEAD; HEAD causes only the latest revision to be pulled.
170 The default is to pull everything.
171
172 hgsubversion.tagpaths
173 Specifies one or more paths in the Subversion repository that
174 contain tags. The default is to only look in `tags`. This option has no
175 effect for single-directory clones.
176
177 Please note that some of these options may be specified as command line options
178 as well, and when done so, will override the configuration. If an authormap,
179 filemap or branchmap is specified, its contents will be read and stored for use
180 in future pulls.