hg-website-content / guide / index.html

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
{% extends "base.html" %}

{% block content %}

<h1>Learning Mercurial in Workflows</h1>

<p>With Mercurial you can use a multitude of different workflows. This page shows some of them, including their use cases. It is intended to make it easy for beginners of version tracking to get going instantly and learn completely incrementally. It doesn't explain the concepts used, because there are already many other great resources doing that. </p>

<p>Alternatives to this guide and further reading: </p>

<ul>
<li> <a title="Mercurial Tutorial" href="http://www.selenic.com/mercurial/wiki/Tutorial">Tutorial</a> - a more exhaustive tutorial. </li>
<li><a title="Mercurial: The definitive Guide" href="http://hgbook.red-bean.com/">Mercurial: The Definitive Guide</a> - a very detailed description of Mercurial including <a title="Behind the Scenes" href="http://hgbook.red-bean.com/read/behind-the-scenes.html">behind the scenes</a>, an indepth article on the design of Mercurial.</li>
<li><a title="Understanding Mercurial" href="http://www.selenic.com/mercurial/wiki/UnderstandingMercurial">Understanding Mercurial</a> - the concepts behind Mercurial.</li>
</ul>

<div class="note">
<p class="note-title">Note:</p>
This guide doesn't require any prior knowledge of version control systems (though subversion users will likely feel at home quite quickly). Basic command line abilities are helpful, because we'll use the command line client. <!--If you already know other systems, please check our transition guides: svn, cvs, git, bzr -->
</div>
<h1 id="basic_workflow">Basic workflows</h1>

<p><em>We go from simple to more complex workflows. Those further down build on previous workflows.</em></p>

<h2 id="log_keeping">Log keeping</h2>

<h3>Use Case</h3>

<p>The first workflow is also the easiest one: You want to use Mercurial to be able to <strong>look back when you did which changes</strong>.</p>

<p>This workflow only requires an installed Mercurial and write access to some file storage (you almost definitely have that :) ). It shows the basic techniques for more complex workflows.</p>

<h3>Workflow</h3>

<h5>Prepare Mercurial</h5>

<p>As first step, you should teach Mercurial your name. For that you open the file ~/.hgrc (or mercurial.ini in your home directory for Windows) with a text-editor and add the ui section (user interaction) with your username:</p>

<pre>[ui]
username = Mr. Johnson &lt;johnson@smith.com&gt;

</pre>

<h5>Initialize the project</h5>

<p>Now you add a new folder in which you want to work:</p>

<pre>$ hg init project

</pre>

<h5>Add files and track them</h5>

<p>Enter the project folder, create some files, then add and commit them.</p>

<pre>$ cd project
$ echo 'print("Hello")' > hello.py
$ hg add
$ hg commit
(enter the commit message)

</pre>

<div class="output">output of hg add:
adding hello.py
</div>

<div class="output">display of hg commit (with your message):
Initial commit.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: Leave message empty to abort commit.
HG: --
HG: user: Mr. Johnson &lt;johnson@smith.com&gt;
HG: branch 'default'
HG: added hello.py
</div>

<p>You can then look into your initial history with <em>hg log</em>:</p>

<pre>$ hg log

</pre>

<div class="output">output of hg log:
changeset:   0:a5ecbf5799c8
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:00:00 2011 +0100
summary:     Initial commit.
</div>


<div class="note">
<p class="note-title">Note:</p>
You can also go into an existing directory with files and init the repository there.

<pre>$ cd project
$ hg init

</pre>

<p>Also you can add only specific files instead of all files in the directory. Mercurial will then track only these files and won't know about the others. The following tells mercurial to track all files whose names begin with "file0" as well as file10, file11 and file12.</p>

<pre>$ hg add file0* file10 file11 file12

</pre>
</div>

<h5>Save changes</h5>

<p>First do some changes:</p>

<pre>$ echo 'print("Hello World") > hello.py

</pre>

<p>see which files changed, which have been added or removed, and which aren't tracked yet</p>

<pre>$ hg status

</pre>

<div class="output">output of hg status:
M hello.py
</div>


<p>see the exact changes</p>

<pre>$ hg diff

</pre>

<div class="output">output of hg diff:
diff --git a/hello.py b/hello.py
--- a/hello.py
+++ b/hello.py
@@ -1,1 +1,1 @@
-print("Hello")
+print("Hello World")
</div>


<p><em>commit</em> the changes.</p>

<pre>$ hg commit

</pre>

<p>now an editor pops up and asks you for a commit message. Upon saving and closing the editor, your changes have been stored by Mercurial.</p>

<div class="output">display of hg commit (with your message):
Say Hello World, not just Hello.

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: Leave message empty to abort commit.
HG: --
HG: user: Mr. Johnson &lt;johnson@smith.com&gt;
HG: branch 'default'
HG: changed hello.py
</div>

<p>Your history now looks like this:</p>

<div class="output">output of hg log:
changeset:   1:487d7a20ccbc
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:11:00 2011 +0100
summary:     Say Hello World, not just Hello.

changeset:   0:a5ecbf5799c8
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:00:00 2011 +0100
summary:     Initial commit.
</div>


<div class="note">
<p class="note-title">Note:</p>
You can also supply the commit message directly via <em>hg commit -m 'MESSAGE'</em>.
</div>

<h5>Copy and move files</h5>

<p>When you copy or move files, you should tell Mercurial to do the copy or move for you, so it can track the relationship between the files.</p>

<p>Remember to <em>commit</em> after moving or copying. From the basic commands only <em>commit</em> creates a new revision</p>

<pre>$ hg cp hello.py copy
$ hg mv hello.py target
$ hg diff # see the changes
$ hg commit
(enter the commit message)

</pre>

<p>Now you have two files, "copy" and "target", and Mercurial knows how they are related.</p>

<div class="output">output of hg diff (before the commit): 
diff --git a/hello.py b/copy
rename from hello.py
rename to copy
diff --git a/hello.py b/target
copy from hello.py
copy to target
</div>

<div class="note">
<p class="note-title">Note:</p>
Should you forget to do the explicit copy or move, you can still tell Mercurial to detect the changes via <em>hg addremove --similarity 100</em>. Just use <em>hg help addremove</em> for details.
</div>

<h5>Check your history</h5>

<pre>$ hg log

</pre>

<p>This prints a list of changesets along with their date, the user who committed them (you) and their commit message. </p>

<div class="output">output of hg log:
changeset:   2:70eb0ca9d264
tag:         tip
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:20:00 2011 +0100
summary:     Copy and move.

changeset:   1:487d7a20ccbc
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:11:00 2011 +0100
summary:     Say Hello World, not just Hello.

changeset:   0:a5ecbf5799c8
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:00:00 2011 +0100
summary:     Initial commit.
</div>

<p>To see a certain revision, you can use the <em>-r</em> switch (--revision). To also see the diff of the displayed revisions, there's the <em>-p</em> switch (--patch)</p>

<pre>$ hg log -p -r 3

</pre>

<h2 id="lone_developer">Lone developer with nonlinear history</h2>

<h3>Use case</h3>

<p>The second workflow is still very easy: You're a lone developer and you want to use Mercurial to <strong>keep track of your own changes</strong> and <strong>optimize your workflow</strong>.</p>

<p>It works just like the log keeping workflow, with the difference that you go back to earlier changes at times and work onwards from there.</p>

<p>To start a new project, you initialize a repository, add your files and commit whenever you finished a part of your work.</p>

<p>Also you check your history from time to time, so see how you progressed.</p>

<h3>Workflow</h3>

<h5>Basics from log keeping</h5>

<p>Init your project, add files, see changes and commit them.</p>

<pre>$ hg init project
$ cd project
$ (add files)
$ hg add # tell Mercurial to track all files
$ (do some changes)
$ hg diff # see changes
$ hg commit # save changes
$ hg cp # copy files or folders
$ hg mv # move files or folders
$ hg log # see history

</pre>

<h5>Seeing an earlier revision</h5>

<p>Different from the log keeping workflow, you'll want to go back in history at times and do some changes directly there, for example because an earlier change introduced a bug and you want to fix it where it occurred.</p>

<p>To look at a previous version of your code, you can use update. Let's assume that you want to see revision 1.</p>

<pre>$ hg update 1

</pre>

<p>Now your code is back at revision 1, the second commit (Mercurial starts counting at 0).
To check if you're really at that revision, you can use <em>identify -n</em>.</p>

<pre>$ hg identify -n

</pre>

<div class="output">output of hg identify -n:
1
</div>

<div class="output">output of ls: 
hello.py
</div>


<div class="note">
<p class="note-title">Note:</p>
<em>identify</em> without options gives you the short form of a unique revision ID. That ID is what Mercurial uses internally. If you tell someone about the version you updated to, you should use that ID, since the numbers can be different for other people. If you want to know the reasons behind that, please read up Mercurials [<a href="http://mercurial.selenic.com/wiki/UnderstandingMercurial">basic concepts</a>]. When you're at the most recent revision, <em>hg identify -n</em> will return "-1".
</div>

<p>To update to the most recent revision, you can use "tip" as revision name.</p>

<pre>$ hg update tip

</pre>

<div class="note">
<p class="note-title">Note:</p>
If at any place any command complains, your best bet is to read what it tells you and follow that advice.
</div>

<div class="note">
<p class="note-title">Note:</p>
Instead of <em>hg update</em> you can also use the shorthand <em>hg up</em>. Similarly you can abbreviate <em>hg commit</em> to <em>hg ci</em>.
</div>

<div class="note">
<p class="note-title">Note:</p>
To get a revision devoid of files, just <em>update</em> to "null" via <em>hg update null</em>. That's the revision before any files were added.
</div>

<div class="note">
<p class="note-title">Note:</p>
If the output of <em>hg identify</em> ends in a “+”, your repository has uncommitted changes.
</div>


<h5>Fixing errors in earlier revisions</h5>

<p>When you find a bug in some earlier revision you have two options: either you can fix it in the current code, or you can go back in history and fix the code exactly where you did it, which creates a cleaner history.</p>

<p>To do it the cleaner way, you first update to the old revision, fix the bug and commit it. Afterwards you merge this revision and commit the merge. Don't worry, though: Merging in mercurial is fast and painless, as you'll see in an instant.</p>

<p>Let's assume the bug was introduced in revision 1.</p>

<pre>$ hg update 1
$ echo 'print("Hello Mercurial")' > hello.py
$ hg commit

</pre>

<div class="output">output of hg commit (after entering the message):
created new head
</div>

<div class="note">
<p class="note-title">Note:</p>
“created new head” means that there is now one more revision, which does not have children. Heads are current states of your project living side by side. It is good style to merge them together before propagating them.
</div>


<p>Now the fix is already stored in history. We just need to merge it with the current version of your code.</p>

<pre>$ hg merge

</pre>

<div class="output">output of hg merge (here):
merging hello.py and copy to copy
merging hello.py and target to target
</div>

<p>If there are conflicts use <em>hg resolve</em> - that's also what merge tells you to do in case of conflicts.</p>

<p>First list the files with conflicts</p>

<pre>$ hg resolve --list

</pre>

<p>Then resolve them one by one. <em>resolve</em> attempts the merge again</p>

<pre>$ hg resolve conflicting_file
(fix it by hand, if necessary)

</pre>

<div class="note">
<p class="note-title">Note:</p>
For more details on resolving conflicts, see the wiki-page <a title="Tutorial - Merging conflicting Changes" href="http://mercurial.selenic.com/wiki/TutorialConflict">TutorialConflict</a>.
</div>


<p>Mark the fixed file as resolved</p>

<pre>$ hg resolve --mark conflicting_file

</pre>

<p>Commit the merge, as soon as you resolved all conflicts. This step is also necessary when there were no conflicts!</p>

<pre>$ hg commit

</pre>

<p>At this point, your fix is merged with all your other work, and you can just go on coding. Additionally the history shows clearly where you fixed the bug, so you'll always be able to check where the bug was.</p>

<div class="output">output of hg log (after the final commit):
changeset:   4:3b06bba7c1a9
tag:         tip
parent:      3:7ff5cd572d80
parent:      2:70eb0ca9d264
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 20:11:00 2011 +0100
summary:     merge greeting and copy+move.

changeset:   3:7ff5cd572d80
parent:      1:487d7a20ccbc
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 20:00:00 2011 +0100
summary:     Greet Mercurial

changeset:   2:70eb0ca9d264
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:20:00 2011 +0100
summary:     Copy and move.

changeset:   1:487d7a20ccbc
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:11:00 2011 +0100
summary:     Say Hello World, not just Hello.

changeset:   0:a5ecbf5799c8
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 11:00:00 2011 +0100
summary:     Initial commit.
</div>


<div class="note">
<p class="note-title">Note:</p>
Most merges will just work. You only need <em>resolve</em>, when <em>merge</em> complains.
</div>

<p>So now you can initialize repositories, save changes, update to previous changes and develop in a nonlinear history by committing in earlier changesets and merging the changes into the current code.</p>

<div class="note">
<p class="note-title">Note:</p>
If you fix a bug in an earlier revision, and some later revision copied or moved that file, the fix will be propagated to the target file(s) when you merge. This is the main reason why you should always use <em>hg cp</em> and <em>hg mv</em>.
</div>

<h2 id="separate_features">Separate features</h2>

<h3>Use Case</h3>

<p>At times you'll be <strong>working on several features in parallel</strong>. If you want to avoid mixing incomplete code versions, you can create clones of your local repository and work on each feature in its own code directory.</p>

<p>After finishing your feature you then <em>pull</em> it back into your main directory and <em>merge</em> the changes.</p>

<h3>Workflow</h3>

<h5>Work in different clones</h5>

<p>First create the feature clone and do some changes</p>

<pre>$ hg clone project feature1
$ cd feature1
$ hg update 3
$ echo 'print("Hello feature1")' > hello.py
$ hg commit -m "Greet feature1"

</pre>

<p>Now check what will come in when you <em>pull</em> from feature1, just like you can use <em>diff</em> before committing. The respective command for pulling is <em>incoming</em></p>

<pre>$ cd ../project
$ hg incoming ../feature1

</pre>

<div class="output">output of hg incoming ../feature1:
comparing with ../feature1
searching for changes
changeset:   5:3eb7b39fcf57
tag:         tip
parent:      3:7ff5cd572d80
user:        Arne Babenhauserheide <bab@draketo.de>
date:        Sun Nov 20 20:11:11 2011 +0100
summary:     Greet feature1
</div>


<div class="note">
<p class="note-title">Note:</p>
If you want to see the diffs, you can use <em>hg incoming --patch</em> just as you can do with <em>hg log --patch</em> for the changes in the repository.
</div>

<p>If you like the changes, you pull them into the project</p>

<pre>$ hg pull ../feature1

</pre>

<p>Now you have the history of feature1 inside your project, but the changes aren't yet visible. Instead they are only stored inside a ".hg" directory of the project (<a title="Behind the Scenes" href="http://hgbook.red-bean.com/read/behind-the-scenes.html">more information on the store</a>).</p>

<div class="output">output of hg pull:
pulling from ../feature1
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
(run 'hg heads' to see heads, 'hg merge' to merge)
</div>

<div class="note">
<p class="note-title">Note:</p>
From now on we'll use the name "repository" for a directory which has a .hg directory with Mercurial history.
</div>

<p>If you didn't do any changes in the project, while you were working on feature1, you can just update to tip (<em>hg update tip</em>), but it is more likely that you'll have done some other changes in between changes. In that case, it's time for merging.</p>

<p>Merge feature1 into the project code</p>

<pre>$ hg merge

</pre>

<p>If there are conflicts use <em>hg resolve</em> - that's also what merge tells you to do in case of conflicts. After you <em>merge</em>, you have to <em>commit</em> explicitly to make your <em>merge</em> final</p>

<pre>$ hg commit
(enter commit message, for example "merged feature1")

</pre>

<div class="output">output of hg log -r -1:-3 (the last 3 changesets):
changeset:   6:e8a33691171a
tag:         tip
parent:      4:3b06bba7c1a9
parent:      5:3eb7b39fcf57
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 20:20:00 2011 +0100
summary:     merged feature1

changeset:   5:3eb7b39fcf57
parent:      3:7ff5cd572d80
user:        Arne Babenhauserheide <bab@draketo.de>
date:        Sun Nov 20 20:11:11 2011 +0100
summary:     Greet feature1

changeset:   4:3b06bba7c1a9
parent:      3:7ff5cd572d80
parent:      2:70eb0ca9d264
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 20:11:00 2011 +0100
summary:     merge greeting and copy+move.
</div>


<div class="note">
<p class="note-title">Note:</p>
Mercurial offers powerful ways specify revisions. Too see them all, use <em>hg help revsets</em>.
</div>


<p>You can create an arbitrary number of clones and also carry them around on USB sticks. Also you can use them to synchronize your files at home and at work, or between your desktop and your laptop.</p>

<div class="note">
<p class="note-title">Note:</p>
You also have to commit after a merge when there are no conflicts, because merging creates new history and you might want to attach a specific message to the merge (like "merge feature1").
</div>

<h5>Rollback mistakes</h5>

<p>Now you can work on different features in parallel, but from time to time a bad commit might sneak in. Naturally you could then just go back one revision and merge the stray error, keeping all mistakes out of the merged revision. However, there's an easier way, if you realize your error before you do another <em>commit</em> or <em>pull</em>: <em>rollback</em>.</p>

<p>Rolling back means undoing the last operation which added something to your history.</p>

<p>Imagine you just realized that you did a bad commit - for example you didn't see a spelling error in a commit message. To fix it you would use</p>

<pre>$ hg rollback

</pre>

<div class="output">output of hg rollback:
repository tip rolled back to revision 5 (undo commit)
working directory now based on revisions 4 and 5
</div>

<p>And then redo the commit</p>

<pre>$ hg commit -m "Merged Feature 1"

</pre>

<div class="output">output of hg log -r -1:-2 (after rollback and commit):
changeset:   6:3f549b33c7ef
tag:         tip
parent:      4:3b06bba7c1a9
parent:      5:3eb7b39fcf57
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 20:20:11 2011 +1100
summary:     Merged Feature 1

changeset:   5:3eb7b39fcf57
parent:      3:7ff5cd572d80
user:        Arne Babenhauserheide <bab@draketo.de>
date:        Sun Nov 20 20:11:11 2011 +0100
summary:     Greet feature1
</div>



<p>If you can use the command history of your shell and you added the previous message via <em>commit -m "message"</em>, that following commit just means two clicks on the arrow-key "up" and one click on "enter".</p>

<p>Though it changes your history, rolling back doesn't change your files. It only undoes the last addition to your history.</p>

<p>But beware, that a rollback itself can't be undone. If you <em>rollback</em> and then forget to commit, you can't just say "give me my old commit back". You have to create a new commit.</p>

<div class="note">
<p class="note-title">Note:</p>
Rollback is possible, because Mercurial uses transactions when recording changes, and you can use the transaction record to undo the last transaction. This means that you can also use <em>rollback</em> to undo your last <em>pull</em>, if you didn't yet commit anything new.
</div>

<h2 id="sharing_changes">Sharing changes</h2>

<h3>Use Case</h3>

<p>Now we go one step further: You are no longer alone, and you want to <strong>share your changes with others and include their changes</strong>.</p>

<p>The basic requirement for that is that you have to be able to see the changes of others.</p>

<p>Mercurial allows you to do that very easily by including a simple webserver from which you can <em>pull</em> changes just as you can pull changes from local clones.</p>

<div class="note">
<p class="note-title">Note:</p>
There are a few other ways to share changes, though. Instead of using the builtin webserver, you can also send the changes by email or setup a shared repository, to where you <em>push</em> changes instead of pulling them. We'll cover one of those later.
</div>

<h3>Workflow</h3>

<h5>Using the builtin webserver</h5>

<p>This is the easiest way to quickly share changes.</p>

<p>First the one who wants to share his changes creates the webserver</p>

<pre>$ hg serve

</pre>

<p>Now all others can point their browsers to his IP address (for example 192.168.178.100) at port 8000. They will then see all his history there and can decide if they want to pull his changes.</p>

<pre>$ firefox http://192.168.178.100:8000

</pre>

<p>If they decide to include the changes, they just pull from the same URL</p>

<pre>$ hg pull http://192.168.178.100:8000

</pre>

<p>At this point you all can work as if you had pulled from a local repository. All the data is now in your individual repositories and you can merge the changes and work with them without needing any connection to the served repository.</p>

<h5>Sending changes by email</h5>

<p>Often you won't have direct access to the repository of someone else, be it because he's behind a restrictive firewall, or because you live in different timezones. You might also want to keep your changes confidential and prefer internal email (if you want additional protection, you can also encrypt the emails, for example with <a href="http://gnupg.org" title="GnuPG">GnuPG</a>).</p>

<p>In that case, you can easily export your changes as patches and send them by email.</p>

<p>Another reason to send them by email can be that your policy requires manual review of the changes when the other developers are used to reading diffs in emails. I'm sure you can think of more reasons.</p>

<p>Sending the changes via email is pretty straightforward with Mercurial. You just <em>export</em> your changes and attach (or copy paste) it in your email. Your colleagues can then just <em>import</em> them.</p>

<p>First check which changes you want to export</p>

<pre>$ cd project
$ hg log

</pre>

<p>We assume that you want to export changeset 3 and 4</p>

<pre>$ hg export 3 > change3.diff
$ hg export 4 > change4.diff

</pre>

<p>Now attach them to an email and your colleagues can just run <em>import</em> on both diffs to get your full changes, including your user information.</p>

<p>To be careful, they first <em>clone</em> their repository to have an integration directory as sandbox</p>

<pre>$ hg clone project integration
$ cd integration
$ hg import change3.diff
$ hg import change4.diff

</pre>

<p>That's it. They can now test your changes in feature clones. If they accept them, they <em>pull</em> the changes into the main repository</p>

<pre>$ cd ../project
$ hg pull ../integration

</pre>

<div class="note">
<p class="note-title">Note:</p>
The <em>patchbomb</em> extension automates the email-sending, but you don't need it for this workflow.
</div>

<div class="note">
<p class="note-title">Note:</p>


You can also send around bundles, which are snippets of your actual history. Just create them via

<pre>$ hg bundle --base FIRST_REVISION_TO_BUNDLE changes.bundle

</pre>

Others can then get your changes by simply pulling them, as if your bundle were an actual repository
<pre>$ hg pull path/to/changes.bundle

</pre>

</div>

<h5>Using a shared repository</h5>

<p>Sending changes by email might be the easiest way to reach people when you aren't yet part of the regular development team, but it creates additional workload: You have to <em>bundle</em> the changes, send mails and then <em>import</em> the bundles manually. Luckily there's an easier way which works quite well: The shared push repository.</p>

<p>Till now we transferred all changes either via email or via <em>pull</em>. Now we use another option: pushing. As the name suggests it's just the opposite of pulling: You <em>push</em> your changes into another repository.</p>

<p>But to make use of it, we first need something we can push to.</p>

<p>By default <em>hg serve</em> doesn't allow pushing, since that would be a major security hole. You can allow pushing in the server, but that's no solution when you live in different timezones, so we'll go with another approach here: Using a shared repository, either on an existing shared server or on a service like <a title="BitBucket" href="http://bitbucket.org">BitBucket</a>. Doing so has a bit higher starting cost and takes a bit longer to explain, but it's well worth the effort spent.</p>

<p>If you want to use an existing shared server, you can use <em>serve</em> there and <a title="How to allow pushing for hg serve" href="http://www.selenic.com/mercurial/wiki/HgWebDirStepByStep#head-746ca383e3a62df34279ec2fca888113497da022">allow pushing</a>. Also there are some other nice ways to <a title="Multiple Committers" href="http://www.selenic.com/mercurial/wiki/MultipleCommitters">allow pushing to a Mercurial repository</a>, including simple <a title="Setting up a shared Mercurial repository using SSH" href="http://www.selenic.com/mercurial/wiki/SharedSSH">access via SSH</a>.</p>

<p>Otherwise you first need to setup a BitBucket Account. Just signup at <a title="BitBucket" href="http://bitbucket.org">BitBucket</a>. After signing up (and login) hover your mouse over "Repositories". There click the item at the bottom of the opening dialog which say "Create new".</p>

<p>Give it a name and a description. If you want to keep it hidden from the public, select "private"</p>

<pre>$ firefox http://bitbucket.org

</pre>

<p>Now your repository is created and you see instructions for <em>push</em>ing to it. For that you'll use a command similar to the following (just with a different URL):</p>

<pre>$ hg push https://bitbucket.org/ArneBab/hello/

</pre>

<p>(Replace the URL with the URL of your created repository. If your username is "Foo" and your repository is named "bar", the URL will be https://bitbucket.org/Foo/bar/)</p>

<p>Mercurial will ask for your BitBucket name and password, then <em>push</em> your code.</p>

<p>Voilà, your code is online.</p>

<p>To see what you would get if you would push, you can use outgoing. It works with local repositories in the same way as with shared ones, so you can test it with a local one:</p>

<pre>$ hg outgoing ../feature1

</pre>

<div class="output">output of hg outgoing ../feature1 (our feature seperation repo):
comparing with ../feature1
searching for changes
changeset:   6:3f549b33c7ef
tag:         tip
parent:      4:3b06bba7c1a9
parent:      5:3eb7b39fcf57
user:        Mr. Johnson <johnson@smith.com>
date:        Sun Nov 20 20:20:11 2011 +1100
summary:     Merged Feature 1
</div>


<div class="note">
<p class="note-title">Note:</p>
You can also <a title="use SSH for pushing to BitBucket" href="http://bitbucket.org/help/UsingSSH">use SSH for pushing to BitBucket</a>.
</div>

<p>Now it's time to tell all your colleagues to sign up at BitBucket, too.</p>

<p>After that you can click the "Admin" tab of your created repository and add the usernames of your colleagues on the right side under "Permission: Writers". Now they are allowed to <em>push</em> code to the repository.</p>

<p>(If you chose to make the repository private, you'll need to add them to "Permission: Readers", too)</p>

<p>If one of you now wants to publish changes, he'll simply <em>push</em> them to the repository, and all others get them by <em>pull</em>ing.</p>

<p>Publish your changes</p>

<pre>$ hg push https://bitbucket.org/ArneBab/hello/

</pre>

<p>Pull others changes into your local repository</p>

<pre>$ hg pull https://bitbucket.org/ArneBab/hello/

</pre>

<p>People who join you in development can also just <em>clone</em> this repository, as if one of you were using <em>hg serve</em></p>

<pre>$ hg clone https://bitbucket.org/ArneBab/hello/ hello

</pre>

<p>That local repository will automatically be configured to pull/push from/to the online repository, so new contributors can just use <em>hg push</em> and <em>hg pull</em> without an URL.</p>

<div class="note">
<p class="note-title">Note:</p>
To make this workflow more scalable, each one of you can have his own BitBucket repository and you can simply <em>pull</em> from the others repositories. That way you can easily establish workflows in which certain people act as integrators and finally <em>push</em> checked code to a shared pull repository from which all others pull.
</div>

<div class="note">
<p class="note-title">Note:</p>
You can also use this workflow with a shared server instead of BitBucket, either via SSH or via a shared directory. An example for an SSH URL with Mercurial is be ssh://user@example.com/path/to/repo. When using a shared directory you just push as if the repository in the shared directory were on your local drive.
</div>

<h2 id="basic_summary">Summary</h2>

<p>Now let's take a step back and look where we are.</p>

<p>With the commands you already know, a bit reading of <em>hg help &lt;command&gt;</em> and some evil script-fu you can already do almost everything you'll ever need to do when working with source code history. So from now on almost everything is convenience, and that's a good thing.</p>

<p>First this is good, because it means, that you can now use most of the concepts which are utilized in more complex workflows.</p>

<p>Second it aids you, because convenience lets you focus on your task instead of focusing on your tool. It helps you concentrate on the coding itself. Still you can always go back to the basics, if you want to.</p>

<p>A short summary of what you can do which can also act as a short check, if you still remember the meaning of the commands.</p>

<h3>create a project</h3>

<pre>$ hg init project
$ cd project
$ (add some files)
$ hg add
$ hg commit
(enter the commit message)

</pre>

<h3>do nonlinear development</h3>

<pre>$ (do some changes)
$ hg commit
(enter the commit message)
$ hg update 0
$ (do some changes)
$ hg commit
(enter the commit message)
$ hg merge
$ (optionally hg resolve)
$ hg commit
(enter the commit message)

</pre>

<h3>use feature clones</h3>

<pre>$ cd ..
$ hg clone project feature1
$ cd feature1
$ (do some changes)
$ hg commit
(enter the commit message)
$ cd ../project
$ hg pull ../feature1

</pre>

<h3>share your repository via the integrated webserver</h3>

<pre>$ hg serve &amp;
$ cd ..
$ hg clone http://127.0.0.1:8000 project-clone

</pre>

<h3>export changes to files</h3>

<pre>$ cd project-clone
$ (do some changes)
$ hg commit
(enter the commit message)
$ hg export tip > ../changes.diff

</pre>

<h3>import changes from files</h3>

<pre>$ cd ../project
$ hg import ../changes.diff

</pre>

<h3>pull changes from a served repository (hg serve still runs on project)</h3>

<pre>$ cd ../feature1
$ hg pull http://127.0.0.1:8000

</pre>

<h3>Use shared repositories on BitBucket</h3>

<pre>$ (setup bitbucket repo)
$ hg push https://bitbucket.org/USER/REPO
(enter name and password in the prompt)
$ hg pull https://bitbucket.org/USER/REPO

</pre>


<p>Let's move on towards useful features and a bit more advanced workflows.</p>

<h1 id="advanced_workflows">Advanced workflows</h1>

<h2 id="backing_out">Backing out bad revisions</h2>

<h3>Use Case</h3>

<p>When you routinely pull code from others, it can happen that you overlook some bad change. As soon as others pull that change from you, you have little chance to get completely rid of it.</p>

<p>To resolve that fundamental problem in any really distributed system, Mercurial offers you the <em>backout</em> command. Backing out a change means, that you tell Mercurial to <strong>create a commit which reverses the bad change</strong>. That way you don't get rid of the bad code in history, but you can remove it from new revisions.</p>

<div class="note">
<p class="note-title">Note:</p>
The basic commands don't rewrite history. If you want to do that, you need to activate some of the extensions which are shipped with mercurial. We'll come to that <a title="Removing History" href="#removing_history">later on</a>.
</div>

<h3>Workflow</h3>

<p>Let's assume the bad change was revision 3, and you already have one more revision in your
repository. To remove the bad code, you can just <em>backout</em> of it. This creates a new
change which reverses the bad change. After backing out, you can then merge that new change
into the current code.</p>

<pre>$ hg backout 3
$ hg merge
(potentially resolve conflicts)
$ hg commit
(enter commit message. For example: "merged backout")

</pre>

<p>That's it. You reversed the bad change. It's still recorded that it was once there (following the principle "don't rewrite history, if it's not really necessary"), but it doesn't affect future code anymore.</p>

<h2 id="collaborative_development">Collaborative feature development</h2>

<p>Now that you can share changes and reverse them if necessary, you can go one step further: Using Mercurial to help in <strong>coordinating the coding</strong>.</p>

<p>The first part is an easy way to develop features together, without requiring every developer to keep track of several feature clones.</p>

<h3>Use Case</h3>

<p>When you want to split your development into several features, you need to keep track of who works on which feature and where to get which changes.</p>

<p>Mercurial makes this easy for you by providing named branches. They are a part of the main repository, so they are available to everyone involved. At the same time, changes committed on a certain branch don't get mixed with the changes in the default branch, so features are kept separate, until they get merged into the default branch.</p>

<div class="note">
<p class="note-title">Note:</p>
Cloning a repository always puts you onto the default branch at first.
</div>

<h3>Workflow</h3>

<p>When someone in your group wants to start coding on a feature without disturbing the others, he can create a named branch and commit there. When someone else wants to join in, he just updates to the branch and commits away. As soon as the feature is finished, someone merges the named branch into the default branch.</p>

<div class="note">
<p class="note-title">Note:</p>
Named branch information is <strong>permanently stored in history</strong>, so you can always see for which feature some change was added. If you only want temporary branches as short-lived markers on history, you can use Bookmarks instead. Just replace <em>hg branch</em> with <em>hg bookmark</em> and add <em>-B &lt;bookmark-name&gt;</em> to <em>hg push</em> and <em>hg pull</em>.
</div>

<h5>Working in a named branch</h5>

<p>Create the branch</p>

<pre>$ hg branch feature1
(do some changes)
$ hg commit
(write commit message)

</pre>

<p>Update into the branch and work in it</p>

<pre>$ hg update feature1
(do some changes)
$ hg commit
(write commit message)

</pre>

<p>Now you can <em>commit</em>, <em>pull</em>, <em>push</em> and <em>merge</em> (and anything else) as if you were working in a separate repository. If the history of the named branch is linear and you call "hg merge", Mercurial asks you to specify an explicit revision, since the branch in which you work doesn't have anything to merge.</p>

<h5>Merge the named branch</h5>

<p>When you finished the feature, you <em>merge</em> the branch back into the default branch.</p>

<pre>$ hg update default
$ hg merge feature1
$ hg commit
(write commit message)

</pre>

<p>To see the active branches with <em>hg branches</em>. To mark a branch as inactive, for example because you finished implementing the feature, you can close it. Closed branches are hidden in <em>hg branches</em> as well as in <em>hg heads</em>.</pre>

<pre>$ hg update feature1
$ hg commit --close-branch -m "finished feature1"

</pre>

<p>And that's it. Now you can easily keep features separate without unnecessary bookkeeping.</p>

<h2 id="tagging">Tagging revisions</h2>

<h3>Use Case</h3>

<p>Since you can now code separate features more easily, you might want to mark certain revisions as fit for consumption (or similar). For example you might want to <strong>mark releases, or just mark off revisions as reviewed</strong>.</p>

<p>For this Mercurial offers tags. Tags add a name to a revision and are part of the history. You can tag a change years after it was committed. The tag includes the information when it was added, and tags can be pulled, pushed and merged just like any other committed change.</p>

<div class="note">
<p class="note-title">Note:</p>
A tag must not contain the char ":", since that char is used for specifying multiple revisions - see "hg help revisions".
</div>

<div class="note">
<p class="note-title">Note:</p>
To securely mark a revision, you can use the <a title="Using GnuPG to securely sign revisions in Mercurial" href="http://www.selenic.com/mercurial/wiki/GpgExtension">gpg extension</a> to sign the tag.
</div>

<h3>Workflow</h3>

<p>Let's assume you want to give revision 3 the name "v0.1".</p>

<p>Add the tag</p>

<pre>$ hg tag -r 3 v0.1

</pre>

<p>See all tags</p>

<pre>$ hg tags

</pre>

<p>When you look at the log you'll now see a line in changeset 3 which marks the Tag. If someone wants to <em>update</em> to the tagged revision, he can just use the name of your tag</p>

<pre>$ hg update v0.1

</pre>

<p>Now he'll be at the tagged revision and can work from there.</p>


<h2 id="removing_history">Removing history</h2>

<h3>Use Case</h3>

<p>At times you will have changes in your repository, which you really don't want in it.</p>

<p>There are many advanced options for removing these, and most of them use great extensions (<a title="Mercurial Queues Extension" href="http://www.selenic.com/mercurial/wiki/MqExtension">Mercurial Queues</a> is the most often used one), but in this basic guide, we'll solve the problem with just the commands we already learned. But we'll use an option to clone which we didn't yet need.</p>

<p>This workflow becomes inconvenient when you need to remove changes, which are buried below many new changes. If you spot the them early enough, you can <strong>get rid of bad changes</strong> without too much effort, though.</p>

<h3>Workflow</h3>

<p>Let's assume you want to get rid of revision 2 and the highest revision is 3.</p>

<p>The first step is to use the "--rev" option to <em>clone</em>: Create a clone which only contains the changes up to the specified revision. Since you want to keep revision 1, you only clone up to that</p>

<pre>$ hg clone -r 1 project stripped

</pre>

<p>Now you can <em>export</em> the change 3 from the original repository (project) and <em>import</em> it into the stripped one</p>

<pre>$ cd project
$ hg export 3 > ../changes.diff
$ cd ../stripped
$ hg import ../changes.diff

</pre>

<p>If a part of the changes couldn't be applied, you'll see that part in *.rej files. If you have *.rej files, you'll have to include or discard changes by hand</p>

<pre>$ cat *.rej
(apply changes by hand)
$ hg commit
(write commit message)

</pre>

<p>That's it. <em>hg export</em> also includes the commit message, date, committer and similar metadata, so you are already done.</p>

<div class="note">
<p class="note-title">Note:</p>
removing history will change the revision IDs of revisions after the removed one, and if you pull from someone else who still has the revision you removed, you will pull the removed parts again. That's why rewriting history should most times only be done for changes which you didn't yet publicise.
</div>

<h2 id="advanced_summary">Summary</h2>

<p>So now you can work with Mercurial in private, and also share your changes in a multitude of ways.</p>

<p>Additionally you can remove bad changes, either by creating a change in the repository which reverses the original change, or by really rewriting history, so it looks like the change never occurred.</p>

<p>And you can separate the work on features in a single repository by using named branches and add tags to revisions which are visible markers for others and can be used to update to the tagged revisions.</p>

<p>With this we can conclude our practical guide.</p>

<h1 id="complex_workflows">More Complex Workflows</h1>

<p>If you now want to check some more complex workflows, please have a look at the general <a title="Mercurial Workflows" href="http://selenic.com/mercurial/wiki/Workflows">workflows wikipage</a> and the list of <a title="Mercurial extensions" href="http://mercurial.selenic.com/wiki/UsingExtensions">extensions</a>.</p>

<p>To deepen your understanding, you should also check the <a title="Overview of the basic concepts of Mercurial" href="http://mercurial.selenic.com/wiki/UnderstandingMercurial">basic concept overview</a>.</p>

<p>Have fun with Mercurial!</p>



{% endblock %}
{% block sidebar %}
	<h1>Index</h1>
	<ul class="sidebar-toc">
	    <li><a href="#basic_workflow">Basic workflows</a></li>
	    <ul>
		<li><a href="#log_keeping">Log keeping</a></li>
		<li><a href="#lone_developer">Lone developer with nonlinear history</a></li>
		<li><a href="#separate_features">Separate features</a></li>
		<li><a href="#sharing_changes">Sharing changes</a></li>
		<li><a href="#basic_summary">Summary</a></li>
	    </ul>
	    <li><a href="#advanced_workflows">Advanced workflows</a></li>
	    <ul>
		<li><a href="#backing_out">Backing out bad revisions</a></li>
		<li><a href="#collaborative_development">Collaborative feature development</a></li>
		<li><a href="#tagging">Tagging revisions</a></li>
		<li><a href="#removing_history">Removing history</a></li>
		<li><a href="#advanced_summary">Summary</a></li>
	    </ul>
	    <li><a href="#complex_workflows">More complex workflows</a></li>
	</ul>

		</div>
	</div>

{% endblock %}
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.