preliminary guide to Mercurial via workflows

[Arne Babenhauserheide]

Hi, 

For mercurial-scm.org I worked on a workflows page which transmutated into a  
guide to Mercurial (there will be an-other workflow page). 

I just post it in this (monster-)email. 

On this guide I'd like to get your feedback: What do you think about it. 

Best wishes, 
Arne

------ learning Mercurial in workflows ------

= Learning Mercurial in Workflows =

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 easier for you to create your own workflow. 

To write this page we gathered [real life workflows](wiki - workflows), so 
every more complex workflow in here has proven itself in real life usage. We 
begin with basic workflows and then go on to more complex examples. 


= Basic workflows =

== Sysadmin workflow ==

=== Use Case ===

The first workflow is also the easiest one: You're a sysadmin and you want to 
use Mercurial to be able to look back when you did which changes. 

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

Note: The name doesn't mean that every sysadmin will only need this simple 
workflow. It was chosen in honor of a [mail]() which reminded us, that this 
simple usage is already a workflow in its own right. 

=== Workflow ===

==== Initialize the project ==== 

<code>$ hg init project</code>

==== Add files and track them ====

<code>$ cd project
$ (add files)
$ hg add </code>

Note: You can also go into an existing directory with files and init the 
repository there.  

$ cd project
$ hg init

You can also just add 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 beginning with "file0" as 
well as file10, file11 and file12. 

$ hg add file0* file10 file11 file12 

==== Save changes ====

$ (do some changes)

see which files changed, which have been added or removed, and which aren't 
tracked yet. 

$ hg status 

see the exact changes. 

$ hg diff 

commit the changes. 

$ hg commit

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. 

Note: You can also supply teh commit message directly via "hg commit -m 
'MESSAGE'"

==== Check your history ====

$ hg log

This prints a list of changesets along with their data, the user who committed 
them (you) and their commit message. 

== Lone developer with linear history == 

=== Use case === 

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. 

It works just like the sysadmin workflow, with the difference that you go back 
to earlied changes at times. 

To start a new project, you initialize a repository, add your files and commit 
whenever you finished a part of your work (atomic commits). 

Also you check your history from time to time, so see how you progressed. 

=== Workflow ===

==== Basics from sysadmin ====

Init your project, add files, see changes and commit them. 

<code>$ 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 log # see history

==== Seeing an earlier revision ====

Different from the sysadmin workflow, you'll want to go back in history at 
times and undo some changes, for example because it introduced a bug. 

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

$ hg update 3

Now your code is back at revision 3, the fourth commit (Mercurial starts 
couting at 0). 

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

$ hg update tip

Note: If at any place any command complains, your best bet is to read what it 
tells you and follow that advice. 

Note: Instead of "hg update" you can also use the shorthand "hg up". Similarly 
you can abbreviate "hg commit" to "hg ci". 

==== Fixing errors in earlier revisions ====

When you find a bug in some earlier revision you have two options: eaither you 
can fix it in the current code, or you can go back in history and fix the code 
exactly where you did it. 

To do so, 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. 

Let's assume the bug was introduced in revision 3. 

$ hg update 3
$ (fix the bug)
$ hg commit

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

$ hg merge

If there are conflicts use "hg resolve" - that's also what merge tells you to 
do in case of conflicts. 

$ hg commit

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. 


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. 

== Seperate features ==

=== Use Case ===

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. 

After finishing your feature you then "pull" it back into your main directory 
and "merge" the changes. 

=== Workflow ===

$ hg clone project feature1
$ cd feature1
$ (do some changes and commits)
$ cd ../project
$ hg pull ../feature1

Now you have the history of feature1 inside your project, but they aren't yet 
visible. Instead they are only stored inside the .hg directory inside the 
project. 

Note: From now on we'll use the name "repository" for a directory which has a 
.hg directory with Mercurial history. 

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

Merge feature1 into the project code: 

$ hg merge

If there are conflicts use "hg resolve" - that's also what merge tells you to 
do in case of conflicts. 

$ hg commit -m "merged feature1"

You can create an arbitrary number of clones and also carry them around on USB 
sticks. Also you can use them to synchronize your work at home and at work. 

== Sharing changes ==

=== Use Case ===

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

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

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

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 "push" changes instead of pulling them. 

=== Workflow ===

==== Using the builtin webserver ====

This is the easiest way to quickly share changes. 

First the one who wants to share his changes creates the webserver

$ hg serve

Now all others can point their browsers to his IP address (i.e. 
192.168.178.100) at port 8000. They will then see all his history there and 
can sdecide if they want to pull his changes. 

$ firefox http://192.168.178.100:8000 

If they decide to include the changes, they just pull from the same URL

$ hg pull http://192.168.178.100:8000 

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. 

==== Sending changes by email ====

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 (be sure to encrypt your emails with GnuPG!). 

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

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. 

Sending the changes via email is pretty straightforward with Mercurial. You 
just "export" your changes and attach (or copy paste) it in your email. Your 
collegues can then just "import" them. 

First check which changes you want to export

$ cd project 
$ hg log

We assume that you want to export changeset 3 and 4: 

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

Now attach them to an email and your collegues can just run "import" on both 
diffs to get your full changes, including your user information. 

To be careful, they first clone their repository to have an integration 
directory: 

$ hg clone project integration
$ cd integration
$ hg import change3.diff
$ hg import change4.diff

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

$ cd ../project
$ hg pull ../integration

Note: The patchbomb extension automates the email-sending, but you don't need 
it for this workflow. 

Note 2: You can also send around bundles, which are snippets of your actual 
history. Just create them via 
$ hg bundle --base FIRST_REVISION_TO_BUNDLE changes.bundle
Others can then get your changes by simply pulling them, as if your bundle 
were an actual  repository
$ hg pull path/to/changes.bundle

==== Using a shared repository ====

Sending changes by mail 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 send mails and then import the changes manually. Luckily 
there's an easier way which works quite well: The shared push repository. 

Till now we transferred all changes either via email or via pull, but there's 
yet another way: pushing. As the name suggests it's just the opposite of 
pulling: You push your changes into another repository. 

But to make use of it, we first need something we can push to. 

By default "hg serve" 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 on BitBucket. Doing so has a bit higher starting 
cost and takes a bit longer to explain, but it's well worth the effort spent. 

For it you first need to setup a BitBucket Account. Just signup there and then 
hover your mouse over "Repositories". There click the item at the bottom of 
the opening dialog which say "Create new". 

Give it a name and a description, and if you want to keep it hidden from the 
public, select "private". 

$ firefox http://bitbucket.org

Now your repository is created and you see instructions to "push" code to it. 
for that you'll use a command similar to the following (just with a different 
URL): 

$ hg push https://bitbucket.org/ArneBab/1w6/

(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/)

Mercurial will ask for your BitBucket password, then push your code. 

Voilà, your code is online. 

Now it's time to tell all your collegues to sign up at BitBucket, too. 

After that you can click the "Admin" tab of your created repository and add 
the names of your collegues on the right side under "Permission: Writers". Now 
they are allowed to push code to the repository. 

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

If one of you now wants to publish changes, he'll simply push them to the 
repository, and all others get them by pulling. 

Publish your changes: 

$ hg push https://bitbucket.org/ArneBab/1w6/

Pull others changes into your local repository: 

$ hg pull https://bitbucket.org/ArneBab/1w6/

People who join you in development can also just clone this repository, as if 
one of you were using "hg serve": 

$ hg clone https://bitbucket.org/ArneBab/1w6/ 1w6

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

Note: To make this workflow more scaleable, each one of you can have his own 
BitBucket repository and you can simply pull from the others repositories. 
That way you can easily establish workflows in which certain people act as 
integrators and finally push checked code to a shared pull repository from 
which all others pull. 

== Summary ==

Now let's take a step back and look where we are. 

With the commands you already know, a bit reading of "hg help <command>" 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. 

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

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

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: 

create a project

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

do nonlinear development

$ (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)

use feature clones

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

share your repository via the integrated webserver

$ hg serve &
$ cd ..
$ hg clone http://127.0.0.1:8000 project-clone

export changes to files

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

import changes from files

$ cd ../project
$ hg import ../changes.diff

pull changes from a served repository (hg serve still runs on project)

$ cd ../feature1
$ hg pull http://127.0.0.1:8000

Use shared repositories on BitBucket 

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


Let's move on towards useful features and a bit more advanced workflows. 

== Backing out bad revisions ==

=== Use Case ===

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. 

To resolve that problem, Mercurial offers you the backout 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. 

Note: 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. 

=== Workflow ===

Let's assume the bad change was revision 3, and we already have one more 
revision in our repository. To remove the bad code, we just backout of it. 
This creates a new change which reverses the bad change. After backing out, we 
merge that new change into the current code. 

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

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

== Collaborative feature development ==

Now that we can share changes and reverse them if necessary, we go one step 
further: Using Mercurial to help in coordinating the coding. 

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

=== Use Case ===

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. 

Mercurial makes this easy for you by providing names 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 into the 
changes in the default branch, so features are kept seperate, until they get 
merged into the default branch. 

=== Workflow ===

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. 

Create a named branch (name: feature1) and work on it: 

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

Update into the branch and work in it: 

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

Now you can commit, pull, push and merge as if they were working in a seperate 
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. 

When you finished the feature, you merge it back into the default branch. 

$ hg update default
$ hg merge feature1
$ hg commit
(write commit message)

And that's it. Now you can easily keep features seperate without unnecessary 
bookkeeping. 

== Marking revisions: tag and sign ==

=== Use Case ===

Since you can now code seperate 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. 

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. 

Note: A tag must not contain the char ":", since that char is used for 
specifying multiple reivions - see "hg help revisions". 

=== Workflow ===

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

Add the tag: 

$ hg tag -r 3 v0.1

See all tags: 

$ hg tags

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

$ hg update v0.1

Now he'll be at the tagged revision and can work from there. 


== Removing history == 

=== Use Case ===

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

There are many advanced options for removing these, and of them most use great 
extensions (Mercurial Queues 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 use. 

This workflow becomes inconvenient when you need to changes, which are buried 
below many new changes. If you spot it early enough, you can get rid of them 
without too much effort, though. 

=== Workflow ===

Let's assume you want to get rid of revision 2 and we have 3 revisions in 
total. 

The first step is to use the "--rev" option to clone: Create a clone which 
only contains the changes up to the specified revision. This means that you 
want to keep revision 1, so we only clone up to that. 

$ hg clone -r 1 project stripped

Now you can export the change 3 from the original repository (project) and 
import it into the stripped one. 

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

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. 

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

That's it. "hg export" also includes the commit message, date, committer and 
similar metadata, so you are already done. 

Note: 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. 

== Summary ==

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

Additionally to that you can also 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 occured. 

And you can seperate 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. 

With this we can conclude our practical guide. 

= More Complex Workflows =

If you now want to check some more compelx workflows, please have a look at 
the general [workflows](workflows) page. 

Have fun with Mercurial! 

------ /learning Mercurial in workflows ------

What do you think about it? Does it serve as practical guide? Is it fit for 
mercurial-scm.org and what would you make better? 

Best wishes, 
Arne

--- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- 
   - singing a part of the history of free software -
              http://infinite-hands.draketo.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
Url : http://selenic.com/pipermail/mercurial/attachments/20090429/2c82d6ad/attachment.pgp