Mercurial > hgsubversion

annotate README @ 646:f12257bf8b91

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
README: document single-directory clones a little.
author Augie Fackler <durin42@gmail.com>
date Fri, 16 Jul 2010 16:50:08 -0500
parents ebecf034e52a
children a8d5eec1326b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
288
982c46e7d167 BitBucket supports having the ReST declaration in a comment.
Augie Fackler <durin42@gmail.com>
parents: 280
diff changeset
1 .. -*-restructuredtext-*-
3
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
2
192
246ca614f04e Promote first heading to a real title.
Martin Geisler <mg@daimi.au.dk>
parents: 191
diff changeset
3 ============
246ca614f04e Promote first heading to a real title.
Martin Geisler <mg@daimi.au.dk>
parents: 191
diff changeset
4 hgsubversion
246ca614f04e Promote first heading to a real title.
Martin Geisler <mg@daimi.au.dk>
parents: 191
diff changeset
5 ============
246ca614f04e Promote first heading to a real title.
Martin Geisler <mg@daimi.au.dk>
parents: 191
diff changeset
6
161
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
7 hgsubversion is an extension for Mercurial that allows using Mercurial
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
8 as a Subversion client.
0
f2636cfed115 Initial import of hgsubversion into a public repository.
Augie Fackler <durin42@gmail.com>
parents:
diff changeset
9
515
9fadbf0686a1 README: updated reason users might want to avoid hgsubversion
Augie Fackler <durin42@gmail.com>
parents: 477
diff changeset
10 At this point, hgsubversion is usable by users reasonably familiar with
9fadbf0686a1 README: updated reason users might want to avoid hgsubversion
Augie Fackler <durin42@gmail.com>
parents: 477
diff changeset
11 Mercurial as a VCS. It's not recommended to dive into hgsubversion as an
9fadbf0686a1 README: updated reason users might want to avoid hgsubversion
Augie Fackler <durin42@gmail.com>
parents: 477
diff changeset
12 introduction to Mercurial, since hgsubversion "bends the rules" a little
9fadbf0686a1 README: updated reason users might want to avoid hgsubversion
Augie Fackler <durin42@gmail.com>
parents: 477
diff changeset
13 and violates some of the typical assumptions of early Mercurial users.
2
89f88df794d3 Cleanup to 80 columns and add a couple of notes on basic use.
Augie Fackler <durin42@gmail.com>
parents: 0
diff changeset
14
5
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
15 Installation
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
16 ------------
161
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
17 You need to have Subversion installed with the SWIG Python bindings
476
64cc119d8a9e README: Mercurial 1.3 is no longer in development
Martin Geisler <mg@lazybytes.net>
parents: 391
diff changeset
18 from Subversion 1.5 or later. You need Mercurial 1.3 or later.
5
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
19
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
20 .. _mercurial: http://selenic.com/repo/hg
53
b61d49e3f91c crew-stable does not have what I need after all. Oops.
Augie Fackler <durin42@gmail.com>
parents: 50
diff changeset
21 .. _mercurial-stable: http://selenic.com/repo/hg-stable
5
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
22 .. _crew: http://hg.intevation.org/mercurial/crew
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
23 .. _crew-stable: http://hg.intevation.org/mercurial/crew-stable
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
24
161
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
25 If you are unfamiliar with installing Mercurial extensions, please see
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
26 the UsingExtensions_ page in the Mercurial wiki. Look at the example
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
27 for specifying an absolute path near the bottom of the page. You want
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
28 to give the path to the top level of your clone of this repository.
5
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
29
477
3855865ba53d README: update URL to Mercurial wiki
Martin Geisler <mg@lazybytes.net>
parents: 476
diff changeset
30 .. _UsingExtensions: http://mercurial.selenic.com/wiki/UsingExtensions
5
0548662e2f34 Add a section on installation.
Augie Fackler <durin42@gmail.com>
parents: 4
diff changeset
31
161
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
32 Before using hgsubversion, I *strongly* encourage you to run the
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
33 automated tests. Just use nose_ if you have it (or ``easy_install
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
34 nose`` if you want it), or use ``python tests/run.py`` to run the
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
35 suite with the conventional test runner. Note that because I use nose,
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
36 there's a lot of stdout spew in the tests right now. The important
47127255145c Wrapped long lines in README.
Martin Geisler <mg@daimi.au.dk>
parents: 149
diff changeset
37 part is that all the tests pass.
30
9867250e0a4a Add a segment on running the tests before use.
Augie Fackler <durin42@gmail.com>
parents: 24
diff changeset
38
9867250e0a4a Add a segment on running the tests before use.
Augie Fackler <durin42@gmail.com>
parents: 24
diff changeset
39 .. _nose: http://code.google.com/p/python-nose/
9867250e0a4a Add a segment on running the tests before use.
Augie Fackler <durin42@gmail.com>
parents: 24
diff changeset
40
3
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
41 Basic Use
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
42 -----------
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
43 Get a new clone of an svn server::
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
44
258
4ab27ddbae51 Updated readme a little bit for the new UI.
Augie Fackler <durin42@gmail.com>
parents: 192
diff changeset
45 $ hg clone <svn URI> [destination]
3
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
46
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
47 Real example::
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
48
391
dbdcb97b38af README: svn+http is outdated.
Augie Fackler <durin42@gmail.com>
parents: 288
diff changeset
49 $ hg clone http://python-nose.googlecode.com/svn nose-hg
3
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
50
646
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
51 Note: there are two slightly different ways of cloning
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
52 repositories. The most common desire is to have all the
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
53 branches/tags/trunk from the svn repo, in which case you should clone
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
54 from one level above trunk (as in the example above.) If you instead
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
55 want to clone just a single directory rather than the complete
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
56 branches/tags/trunk structure of the repo, clone the specific
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
57 directory path. In the example above, to get *only* trunk, you would
f12257bf8b91 README: document single-directory clones a little.
Augie Fackler <durin42@gmail.com>
parents: 565
diff changeset
58 clone `http://python-nose.googlecode.com/svn/trunk`.
113
31923684e4dc Better note on how to pull a repository.
John Paulett <john.paulett@gmail.com>
parents: 53
diff changeset
59
3
735fdc6c130a Change the readme to be reST.
Augie Fackler <durin42@gmail.com>
parents: 2
diff changeset
60 Pull new revisions into an already-converted repo::
2
89f88df794d3 Cleanup to 80 columns and add a couple of notes on basic use.
Augie Fackler <durin42@gmail.com>
parents: 0
diff changeset
61
258
4ab27ddbae51 Updated readme a little bit for the new UI.
Augie Fackler <durin42@gmail.com>
parents: 192
diff changeset
62 $ hg pull
2
89f88df794d3 Cleanup to 80 columns and add a couple of notes on basic use.
Augie Fackler <durin42@gmail.com>
parents: 0
diff changeset
63
191
0e912d37cbab Mark command line and svn:externals as literal text.
Martin Geisler <mg@daimi.au.dk>
parents: 190
diff changeset
64 For more information, see ``hg help svn`` while in a converted repo.
177
71d170253a6f README: document svn:externals support
Patrick Mezard <pmezard@gmail.com>
parents: 161
diff changeset
65
191
0e912d37cbab Mark command line and svn:externals as literal text.
Martin Geisler <mg@daimi.au.dk>
parents: 190
diff changeset
66 Support for ``svn:externals``
0e912d37cbab Mark command line and svn:externals as literal text.
Martin Geisler <mg@daimi.au.dk>
parents: 190
diff changeset
67 -----------------------------
0e912d37cbab Mark command line and svn:externals as literal text.
Martin Geisler <mg@daimi.au.dk>
parents: 190
diff changeset
68 All ``svn:externals`` properties are serialized into a single
565
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
69 ``.hgsvnexternals`` file having the following syntax::
190
078425d0187d Fix reST syntax error in README.
Martin Geisler <mg@daimi.au.dk>
parents: 189
diff changeset
70
078425d0187d Fix reST syntax error in README.
Martin Geisler <mg@daimi.au.dk>
parents: 189
diff changeset
71 [.]
565
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
72 common1 http://path/to/external/svn/repo1
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
73 ...additional svn:externals properties lines...
190
078425d0187d Fix reST syntax error in README.
Martin Geisler <mg@daimi.au.dk>
parents: 189
diff changeset
74 [dir2]
565
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
75 common2 -r123 http://path/to/external/svn/repo2
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
76 ...additional svn:externals properties lines...
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
77
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
78 A header line in brackets specifies the directory the property applies
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
79 to, where '.' indicates the project root directory. The property content
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
80 follows the header, **with every content line being prefixed by a single
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
81 space**. Note that the property lines have a format identical to
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
82 svn:externals properties as used in Subversion, and do not support the
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
83 hgsubversion extended svn+http:// URL format.
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
84
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
85 Issuing the command ``hg svn updateexternals`` with the
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
86 ``.hgsvnexternals`` example above would fetch the latest revision of
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
87 repo1 into the subdirectory ./common1, and revision 123 of repo2 into
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
88 dir2/common2. Note that ``.hgsvnexternals`` must be tracked by Mercurial
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
89 before this will work. If ``.hgsvnexternals`` is created or changed, it
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
90 will not be pushed to the related Subversion repository, *but its
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
91 contents will be used to update ``svn:externals`` properties on the
ebecf034e52a README: improved documentation of svn:externals support
Mark Edgington <edgimar@gmail.com>
parents: 515
diff changeset
92 related Subversion repository*.