← Back to branch summary

~ubuntu-branches/ubuntu/utopic/xen/utopic

« back to all changes in this revision

Viewing changes to docs/misc/hg-cheatsheet.txt

  • Committer: Bazaar Package Importer
  • Author(s): Bastian Blank
  • Date: 2010-05-06 15:47:38 UTC
  • mto: (1.3.1) (15.1.1 sid) (4.1.1 experimental)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20100506154738-agoz0rlafrh1fnq7
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/misc/hg-cheatsheet.txt
 
1
 
 
2
Mercurial(hg) Cheatsheet for Xen
 
3
================================
 
4
 
 
5
Written by Andrew Warfield, extended by Michael Fetterman and Ian Pratt
 
6
June 29, 2005, extended by Grzegorz Milos 04 July 2005.
 
7
 
 
8
Overview
 
9
--------
 
10
The Xen project has moved from BitKeeper to Mercurial for source
 
11
control.  This note aims to provide a quick guide to getting up and
 
12
running with the new tools as quickly as possible, and is written from
 
13
the perspective of someone who has been using BK.
 
14
 
 
15
For a more detailed exposition, see the mercurial tutorial:
 
16
 http://www.serpentine.com/mercurial/index.cgi?Tutorial
 
17
 
 
18
The Hg manpage is available at:
 
19
 http://www.selenic.com/mercurial/hg.1.html
 
20
 
 
21
There's also a very useful FAQ that explains the terminology:
 
22
 http://www.selenic.com/mercurial/FAQ.html
 
23
 
 
24
There's also a good README:
 
25
 http://www.selenic.com/mercurial/README
 
26
 
 
27
Necessary software
 
28
------------------
 
29
Mercurial is available at:
 
30
  http://www.selenic.com/mercurial/ 
 
31
 
 
32
You will also need a Python version >= 2.3
 
33
 
 
34
How Mercurial is different from BK
 
35
----------------------------------
 
36
There are several pertinent differences between hg and bk.  This
 
37
section aims to give an overview of the conceptual differences between
 
38
the two SCMs -- if you just want examples to get going, skip ahead to
 
39
"Getting Xen". The key differences are:
 
40
 
 
41
  - No explicit per-file locking.  You do not need to explicitly 
 
42
    check a file out before editing it.
 
43
  - No notion (currently) of file renames.
 
44
  - A repository can have multiple active heads.
 
45
  - Automatic merge support is currently inferior to BK's.
 
46
  - No graphical tools.
 
47
  - No per-file revision history, only per-changeset (we never really used this anyhow)
 
48
  - Hg repositories tend to be rather bigger than Bk ones, but Hg does seem faster.
 
49
 
 
50
Mercurial is based on the notion of changesets as complete, immutable,
 
51
versions of the repository.  You make changes to a working version of
 
52
the repository that is based on a particular changeset.  When you
 
53
commit, you will generate a new child changeset with whatever changes
 
54
you choose to apply.
 
55
 
 
56
A major difference between Hg and BK is that you aren't forced to
 
57
resolve conflicts immediately: BK forced you to resolve conflicts
 
58
immediately on any merge, and it then immediately created a changeset
 
59
with those conflicts' resolutions.  Frequently, you then had to add
 
60
yet another changeset to fixup the things for which the automatic
 
61
merge yielded bad results. Hg puts the results of the merge into your
 
62
work directory, and remembers what you merged with (so that it can
 
63
later record both of the merge parents, if you decide to make a
 
64
changeset), but it doesn't immediately create a changeset.
 
65
 
 
66
A further feature of Hg is that it allows a repository to have
 
67
multiple heads. This means that you can have changesets with no common
 
68
descendent in one repository -- something BK won't allow. This is
 
69
actually pretty neat. For example, it would in principle enable you to
 
70
have both the 2.0-testing and unstable trees in a single
 
71
repository. We shyed away from doing this as we thought the risk of
 
72
committing to the wrong head was too great.
 
73
 
 
74
One slightly confusing aspect of Hg is that many of the commands have
 
75
aliases, and hence when looking things up in the man page its not
 
76
always obvious what the underlying command is. For example 'co' is
 
77
actually an alias for the 'update' command, but 'co' seems to make
 
78
more sense, at least to RCS refugees like me.
 
79
 
 
80
 
 
81
Getting Xen
 
82
-----------
 
83
 
 
84
The URL for the mainline Xen mercurial repository is:
 
85
 
 
86
   http://xenbits.xensource.com/xen-unstable.hg
 
87
   (similarly for xen-2.0 and xen-2.0-testing)
 
88
 
 
89
You can point a browser and this and use Hg's web interface to view
 
90
revision history, or use it as the nominated source when issuing
 
91
"hg init" or "hg pull" commands. 
 
92
 
 
93
However, to avoid taxing the Mercurial server with a complete pull of
 
94
the Xen repository, it is best to download a tarball of a seed
 
95
repository from:
 
96
 
 
97
  http://www.cl.cam.ac.uk/Research/SRG/netos/xen/downloads/xen-unstable.hg.tar.gz
 
98
 
 
99
  (or copy from /usr/groups/netos/html/xen/downloads/xen-unstable.hg.tar.gz)
 
100
 
 
101
Untar the repository on your disk, cd into it, and then pull the most
 
102
recent changes:
 
103
 
 
104
  hg pull -u
 
105
 
 
106
By default hg does not automatically checkout ('update') files from
 
107
the repository as used to happen with bk. The above is equivalent to
 
108
"hg pull; hg co"
 
109
 
 
110
The repository parent is stored in a repository configuration file, 
 
111
.hg/hgrc, from the repository root.  If you look at this file, you 
 
112
will see:
 
113
 
 
114
  |  [paths]
 
115
  |  default = http://xenbits.xensource.com/xen-unstable.hg
 
116
 
 
117
"default" specifies the appropriate parent repository for hg to pull 
 
118
from.  Hg allows you to pull additional repositories, for instance if 
 
119
you want to work between unstable and testing concurrently.
 
120
 
 
121
The command "hg pull" simply adds changesets to your repository,
 
122
without any merging of any kind.  "hg pull -u" implies merging with
 
123
the current state of your working directory.  If you weren't already
 
124
"updated" to your local repository's tip, you might be surprised to
 
125
find yourself merging the results of the pull with a non-tip node in
 
126
your local repository. 
 
127
 
 
128
 
 
129
Revision History
 
130
----------------
 
131
 
 
132
You can view the repository revision history with:
 
133
 
 
134
   hg history
 
135
 
 
136
In practice, you'll probably want to use pipe the output through
 
137
'head' or 'more' as it prints the entire history.
 
138
 
 
139
Looking at the first few lines of output, you can see the changeset at
 
140
the head of the current branch, known as the 'tip' (the tip is
 
141
automatically given a special tag to make it easy to refer to):
 
142
 
 
143
   | changeset:   5599:6cbf9ec05cd9e05c0c46a85df7fc00262633cd3d
 
144
   | tag:         tip
 
145
   | user:        kaf24@firebug.cl.cam.ac.uk
 
146
   | date:        Tue Jun 28 18:47:14 2005
 
147
   | summary:     bitkeeper revision 1.1768 (42c18d2259NPELcGV7ohyZNh72ufSw)
 
148
 
 
149
By default, Hg just shows the first line of the changset comments. You
 
150
can find further information with "hg -v history".
 
151
 
 
152
The changeset identifier has two parts, a _local_ monotonically
 
153
increasing changeset id, 5599 above, and a _global_ hash, which
 
154
follows the colon on the changeset line.  The hash uniquely identifies
 
155
the changeset and its lineage back to the root of the changeset tree
 
156
-- it is useful for distributed management and so on.  However, as it
 
157
is a bit unruly, the local id will allow you to work easily with the
 
158
local repo. Hg commands will take either identifier. Additionally, a
 
159
tags mechanism lets you give common names to specific changesets.
 
160
 
 
161
You should always use the global hash when referring to versions of
 
162
the mainline Xen respoitory. With Bk you could often get away with
 
163
using the shortform version, but with Hg the local ids are pretty much
 
164
guaranteed to be different.
 
165
 
 
166
 
 
167
Creating a child repository from an existing repository
 
168
-------------------------------------------------------
 
169
If you wanted to create additional local child repositories,
 
170
 
 
171
   hg init [path or url]
 
172
 
 
173
is effectively equivalent to bk clone.  The major difference is that 
 
174
it should be run from the root of your new repository.  So:
 
175
 
 
176
   bk clone /foo/bar
 
177
 
 
178
would be replaced with:
 
179
 
 
180
   mkdir bar
 
181
   cd bar
 
182
   hg init /foo/bar
 
183
 
 
184
NB: newer version of Hg support a 'clone' command that works in the
 
185
same manner as bk.
 
186
 
 
187
Editing files
 
188
-------------
 
189
 
 
190
Normal edits may be made in place.  File creation needs explicit
 
191
marking, though deletes should be picked up automatically
 
192
 
 
193
creation:
 
194
 
 
195
   touch a.txt (or otherwise created a file)
 
196
   hg add a.txt
 
197
 
 
198
You can see what has changed using:
 
199
 
 
200
   hg status
 
201
 
 
202
   | C foo/foo.c
 
203
   | R foo/bar.c
 
204
   | ? a.txt
 
205
 
 
206
This shows that in the current repo, foo.c has been changed, bar.c has
 
207
been deleted, and a.txt is new, but has not been added.  '?' changes
 
208
to 'A' after "hg add a.txt". There is a .hgignore file which contains
 
209
regexps of files that should be ignored when scanning for new
 
210
files. We try to ensure that all the generated files in a build are
 
211
covered by the regexps.
 
212
 
 
213
You can add all the new files in a repository with "hg addremove". If
 
214
you discover that you've added a file you didn't want, you can remove
 
215
it from the list of files to be included in the next commit using
 
216
"hg forget".
 
217
 
 
218
Committing changes
 
219
-----------------
 
220
 
 
221
After you've checked that hg knows about any new files you've created,
 
222
you probably want to see a diff of what you're about to commit. You
 
223
can do this with:
 
224
   
 
225
   hg diff
 
226
 
 
227
Once you're happy with what you have, invoke:
 
228
 
 
229
   hg commit
 
230
 
 
231
This will pop up an editor with a list of files to be committed to the
 
232
repository.  It will look vaguely like this:
 
233
 
 
234
   | 
 
235
   | HG: manifest hash 6397b04bd5c2a992482d973b685a7e5e498788e7
 
236
   | HG: changed doc/thesis/new.tex
 
237
   | HG: removed doc/2005-hotdep-protection/paper.tex
 
238
 
 
239
Your comments can go anywhere in this file.  The first line is the 
 
240
most important, as it will show as the changeset description in 
 
241
non-verbose-mode history listings.
 
242
 
 
243
You can do commits without the editor and of partial sets of files 
 
244
using command-line switches. See:
 
245
 
 
246
   hg help commit
 
247
 
 
248
You can use the -A (--addremove) flag to commit e.g. "hg -A commit" to
 
249
ask mercurial to scan the tree looking for newly created files to add
 
250
in to the changeset. This avoids having to explicitly use "hg add",
 
251
but you probably want to be careful of adding any new generated files
 
252
too.
 
253
 
 
254
 
 
255
Generating a patch
 
256
------------------
 
257
Generating a patch is easy,
 
258
 
 
259
   hg export [changeset]
 
260
 
 
261
will generate a patch describing the diff between that changeset and 
 
262
its parent.
 
263
    
 
264
To generate a patch between two specified revisions use:
 
265
   hg diff -r A -r B [files]
 
266
NB: BK syntax -rA..B isn't supported by Hg.   
 
267
 
 
268
 
 
269
Pushing changesets to a parent repository
 
270
-----------------------------------------
 
271
 
 
272
   hg push
 
273
 
 
274
Pushes changes up to a parent. You can't push if you pulled the
 
275
repository off the web interface. In fact, you can currently only push
 
276
to an ssh target -- filesystem directory targets don't work, but this
 
277
will be fixed soon.
 
278
For now it is possible to set up asymmetric pull/push paths. Pulls can
 
279
be done via web interface while pushes via ssh. Example of .hg/hgrc config
 
280
file:
 
281
  | [paths]
 
282
  | default = http://your.server/repository_name
 
283
  | default-push = ssh://[username@]your.server//repository_location
 
284
 
 
285
 
 
286
Repository history
 
287
------------------
 
288
 
 
289
Here are a collection of common commands to get you started:
 
290
 
 
291
   hg history | less
 
292
 
 
293
shows the history of changesets, starting from the most recent.  You 
 
294
want to pipe it to some sort of pager.  For more complete details,
 
295
 
 
296
   hg -v history | less
 
297
 
 
298
will include files modified and full (not just first-line) comments.
 
299
 
 
300
Additionally, you can see just the tip (head of the current
 
301
branch) of the repository by typing:
 
302
 
 
303
   hg [-v] tip
 
304
 
 
305
 
 
306
Moving to a specific changeset
 
307
------------------------------
 
308
 
 
309
The co command lets you change the working version of the repository
 
310
to a different changeset. 
 
311
 
 
312
   hg co [changeset]
 
313
 
 
314
NB: 'co' is an alias for 'update'
 
315
 
 
316
This command enables you to rewind the working repository to previous
 
317
changesets, for example to isolate the changeset in which a bug is
 
318
introduced.
 
319
 
 
320
If you try and do a 'co' but have modified files in your repository Hg
 
321
won't let you unless you ask it explicitly to merge the checked out
 
322
version into the current tree using the "-m" option. The "-C"
 
323
(--clean) option will force overwrite any locally modified files.
 
324
 
 
325
Any commits that are made to non-head changesets will obviously fork
 
326
the tree, creating a new head. You can see all the heads in a tree with
 
327
"hg heads".
 
328
 
 
329
In general, "hg co" does the right thing, although it doesn't
 
330
currently seem to clean up unused directories that have been created
 
331
by other checked-out versions. This can confuse the Xen build
 
332
system. Hg will probably get fixed soon, but in the meantime you can
 
333
cleanup with "find -depth -type d -print | xargs -r rmdir".
 
334
 
 
335
You can return to the tip by omitting an explicit changeset id.
 
336
   
 
337
The manifest command lets you see the contents of the repository for 
 
338
the current changeset.
 
339
 
 
340
   hg manifest
 
341
 
 
342
This will print a bunch of records of the form: 
 
343
 
 
344
   | 98856c45c35a504bc6da06a62b7787ddfdfd1c8b 644 COPYING
 
345
   | f28971eedc5b54e7a9b26dd18d52992955354981 644 Config.mk
 
346
   | a3575cc4db59e50bbac8a039a0c74f081a8dfc4f 644 Makefile
 
347
   | 7fc869aae2945a9f4626fad96552db3103e61cb9 644 README
 
348
   | ...
 
349
 
 
350
This lists the hash of each file, its 1-bit 'executable' attribute
 
351
(either file permission mode 644 or 755), and the file name.  So, to
 
352
determine the files that change across two changesets, you would dump
 
353
the respective manifests to files, and use diff.
 
354
 
 
355
 
 
356
Managing changeset tags
 
357
-----------------------
 
358
To create a tag to the current changeset:
 
359
 
 
360
   hg tag tagname
 
361
 
 
362
This will _immediately_ generate a changeset with a change to the file
 
363
.hgtags in the repository root.   The new tag in this file will look
 
364
something like:
 
365
 
 
366
   | 35159ed4b30538e7a52c60ad0a63f7e9af156e4c tagname
 
367
 
 
368
and may be used to identify that changeset throughout the repo.
 
369
Storing tags in this file and generating changesets immediately 
 
370
forces people to merge and keep tags up to date across the repository.
 
371
 
 
372
Note that tags are resolved by searching .hgtags in each of the 
 
373
repository heads, sequentially, and using the first match.  "hg heads"
 
374
lists the current heads.
 
375
 
 
376
The "hg tags" command, will lists all the currently valid tags.
 
377
 
 
378
 
 
379
Hg server and source browser
 
380
----------------------------
 
381
 
 
382
   hg serve -p port
 
383
 
 
384
Launches a web server on the specified port, serving a source browser 
 
385
for the repository.  This browser may be used to examine the 
 
386
changeset history, view annotated source files, generate diffs.  
 
387
Additionally "hg pull" may be run against it.
 
388
 
 
389
Additional useful commands
 
390
(that probably only need one-line descriptions)
 
391
-----------------------------------------------
 
392
 
 
393
(Slightly) more detail on all of these is available with
 
394
 
 
395
  hg help [command]
 
396
 
 
397
Shows the differences between whatever changeset you most recently
 
398
checked out, and your current working directory:
 
399
 
 
400
   hg diff 
 
401
 
 
402
View an annotated version of a source file:
 
403
 
 
404
   hg annotate
 
405
 
 
406
Get a historical version of a file:
 
407
 
 
408
   hg cat
 
409
 
 
410
 NB: Most commands accepting a version number want the changeset's
 
411
 version number.  "hg cat" is different in that it wants the
 
412
 *file*'s version number.
 
413
 
 
414
Unadd a file to the current commit:
 
415
 
 
416
   hg forget
 
417
 
 
418
List all heads in the current repository:
 
419
 
 
420
   hg heads
 
421
 
 
422
Undo exactly one (and ONLY one) changeset:
 
423
 
 
424
   hg undo
 
425
 
 
426
Show the parents of a changeset:
 
427
 
 
428
   hg parents
 
429
 
 
430
 NB: Changesets have either one or two parent changesets. If your
 
431
 working directory contains the uncommitted results of a merge, then
 
432
 you have two parents.  Otherwise, the single parent is the changeset
 
433
 which you most recently checked out.
 
434
 
 
435
Show the revision history for a single file
 
436
 
 
437
   hg [-v] log <filename>
 
438