hg-website-rendered / 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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
       "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <link href="/css/styles.css" type="text/css" rel="stylesheet">
        <script type="text/javascript" src="/js/typeface.js"></script>
        <script type="text/javascript" src="/js/optimer_regular.typeface.js"></script>
        <script type="text/javascript" src="/js/common.js"></script>
        <script type="text/javascript" src="/sources.js"></script>
        <script type="text/javascript" src="/js/download.js"></script>
        <script language="javascript">
          Downloader.init(sources);
          var dl = Downloader.select();
        </script>
        <link rel="shortcut icon" type="image/x-icon" href="/images/favicon.ico">

        <title>Mercurial SCM</title>
    </head>
    <body id="home">
        <h1 id="logo"><a href="/">mercurial</a></h1>
            
        <ul id="nav" class="typeface-js">
            <li><a href="/about/">about</a></li>
            <li><a href="/guide/">guide</a></li>
            <li><a href="/downloads/">download</a></li>
            <li><a href="http://mercurial.selenic.com/wiki/UsingExtensions">extensions</a></li>
            <li><a href="http://mercurial.selenic.com/wiki/">news/wiki</a></li>
            <li><a href="/sponsors/">sponsors</a></li>
        </ul>
        
        <form id="search" method="get" action="http://mercurial.selenic.com/wiki/Mercurial">
        <input type="hidden" name="action" value="fullsearch">
        <input type="hidden" name="context" value="180">
            <fieldset>
                <legend>Search form</legend>
                <label for="keyword">keyword</label>
                <input class="text" type="text" name="value"
                value="Search the Wiki" id="keyword" onclick="resetBar();">
                <input class="submit" type="submit" value="Title"
                name="titlesearch" alt="Search Titles"> 
            </fieldset>
        </form>
        
        <div id="content">
            
                <div class="row">
                    <div class="col big">
                        

<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, for example <a title="Understanding Mercurial" href="http://www.selenic.com/mercurial/wiki/UnderstandingMercurial">the wiki</a> and <a title="Behind the Scenes" href="http://hgbook.red-bean.com/read/behind-the-scenes.html">the hgbook</a>.</p>

<p>If you want a more exhaustive tutorial with the basics, please have a look at the <a title="Mercurial Tutorial" href="http://www.selenic.com/mercurial/wiki/Tutorial">Tutorial in the Mercurial Wiki</a>. For a really detailed and very nice to read description of Mercurial, please have a look at <a title="Mercurial: The definitive Guide" href="http://hgbook.red-bean.com/">Mercurial: The Definitive Guide</a>.</p>

<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 look back when you did which changes.</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>

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

</pre>

<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>Alternatively 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>

<pre>$ (do some changes)

</pre>

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

<pre>$ hg status

</pre>

<p>see the exact changes</p>

<pre>$ hg diff

</pre>

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

<h5>Move and copy 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 original copy
$ hg commit
(enter the commit message)
$ hg mv original target
$ 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="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>

<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 keep track of your own changes.</p>

<p>It works just like the log keeping workflow, with the difference that you go back to earlier changes at times.</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 3.</p>

<pre>$ hg update 3

</pre>

<p>Now your code is back at revision 3, the fourth 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="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>

<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 3.</p>

<pre>$ hg update 3
$ (fix the bug)
$ hg commit

</pre>

<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>

<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>

<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="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 working on several features in parallel. 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
$ (do some changes and commits)

</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="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="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>

<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 label. To fix it you would use</p>

<pre>hg rollback

</pre>

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

<pre>hg commit -m "message"

</pre>

<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 share your changes with others and include their changes.</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>

<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 problem, Mercurial offers you the <em>backout</em> command. Backing out a change means, that you tell Mercurial to create a commit which reverses the bad change. 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 directly 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 later on.
</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 coordinating the coding.</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>

<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>

<div class="note">
<p class="note-title">Note:</p>
Named branches stay in history as permanent record after you finished your work. If you don't like having that record in your history, please have a look at some of the advanced <a title="Mercurial Workflows" href="http://www.selenic.com/mercurial/wiki/Workflows">workflows</a>.
</div>

<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 mark releases, or just mark off revisions as reviewed.</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 bad changes early enough, you can get rid of them 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>.</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>




                    </div>
                    <div class="col">
                        
	<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>


                    </div>
                </div>
            
        </div>
        
        <div id="footer">
            design by <a href="http://www.designpunct.ro">punct</a> /
            design courtesy of <a href="http://www.bitbucket.org/">bitbucket</a> /
            licensed under <a href="http://www.gnu.org/licenses/gpl-2.0.txt">GPLv2</a> /
            <a href="/thepage/">about this page</a>
        </div>
        
    </body>
</html>
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.