# HG changeset patch # User Arne Babenhauserheide # Date 1252406706 -7200 # Node ID ee2c1a02c6933e9d33f071cddbe270ec44839c47 # Parent b17731a54e2aed5d88c4de6f7d693bfa4b0352eb workflow_guide: Use command to mark hg commands. diff -r b17731a54e2a -r ee2c1a02c693 hgscm/templates/workflow_guide.html --- a/hgscm/templates/workflow_guide.html Tue Sep 08 12:41:51 2009 +0200 +++ b/hgscm/templates/workflow_guide.html Tue Sep 08 12:45:06 2009 +0200 @@ -84,7 +84,7 @@ -

commit the changes.

commit the changes.

$ hg commit
 
@@ -92,13 +92,13 @@
 
 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 the commit message directly via hg commit -m 'MESSAGE'.
+Note: You can also supply the commit message directly via hg commit -m 'MESSAGE'.
 
 Move and copy files
 
 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.
 
-Remember to commit after moving or copying. From the basic commands only commit creates a new revision
+Remember to commit after moving or copying. From the basic commands only commit creates a new revision
 
 $ hg cp original copy
 $ hg commit
@@ -111,7 +111,7 @@
 
 Now you have two files, "copy" and "target", and Mercurial knows how they are related.
 
-Note: Should you forget to do the explicit copy or move, you can still tell Mercurial to detect the changes via hg addremove --similarity 100. Just use hg help addremove for details.
+Note: Should you forget to do the explicit copy or move, you can still tell Mercurial to detect the changes via hg addremove --similarity 100. Just use hg help addremove for details.
 
 Check your history
 
@@ -121,7 +121,7 @@
 
 This prints a list of changesets along with their date, the user who committed them (you) and their commit message. 
 
-To see a certain revision, you can use the -r switch (--revision). To also see the diff of the displayed revisions, there's the -p switch (--patch)
+To see a certain revision, you can use the -r switch (--revision). To also see the diff of the displayed revisions, there's the -p switch (--patch)
 
 $ hg log -p -r 3
 
@@ -169,13 +169,13 @@
 
 
 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 identify -n.
+To check if you're really at that revision, you can use identify -n.
 
 $ hg identify -n
 
 
 
-Note: identify 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 [basic concepts](). When you're at the most recent revision, hg identify -n will return "-1".
+Note: identify 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 [basic concepts](). When you're at the most recent revision, hg identify -n will return "-1".
 
 To update to the most recent revision, you can use "tip" as revision name.
 
@@ -185,9 +185,9 @@
 
 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.
+Note: Instead of hg update you can also use the shorthand hg up. Similarly you can abbreviate hg commit to hg ci.
 
-Note: To get a revision devoid of files, just update to "null" via hg update null. That's the revision before any files were added.
+Note: To get a revision devoid of files, just update to "null" via hg update null. That's the revision before any files were added.
 
 Fixing errors in earlier revisions
 
@@ -209,7 +209,7 @@
 
 
 
-If there are conflicts use hg resolve - that's also what merge tells you to do in case of conflicts.
+If there are conflicts use hg resolve - that's also what merge tells you to do in case of conflicts.
 
 First list the files with conflicts
 
@@ -217,7 +217,7 @@

Then resolve them one by one. resolve attempts the merge again

Then resolve them one by one. resolve attempts the merge again

$ hg resolve conflicting_file
 (fix it by hand, if necessary)
@@ -238,11 +238,11 @@
 
 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.
 
-Note: Most merges will just work. You only need resolve, when merge complains.
+Note: Most merges will just work. You only need resolve, when merge complains.
 
 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.
 
-Note: 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 hg cp and hg mv.
+Note: 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 hg cp and hg mv.
 
 Separate features
 
@@ -250,7 +250,7 @@
 
 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.
+After finishing your feature you then pull it back into your main directory and merge the changes.
 
 Workflow
 
@@ -264,14 +264,14 @@

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

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

$ cd ../project
 $ hg incoming ../feature1

Note: If you want to see the diffs, you can use hg incoming --patch just as you can do with hg log --patch for the changes in the repository.

Note: If you want to see the diffs, you can use hg incoming --patch just as you can do with hg log --patch for the changes in the repository.

If you like the changes, you pull them into the project

@@ -283,7 +283,7 @@

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.

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

@@ -291,7 +291,7 @@ -

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

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

$ hg commit
 (enter commit message, for example "merged feature1")
@@ -304,7 +304,7 @@
 
 Rollback mistakes
 
-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 commit or pull: rollback.
+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 commit or pull: rollback.
 
 Rolling back means undoing the last operation which added something to your history.
 
@@ -320,13 +320,13 @@

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

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

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

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

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

Note: 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 rollback to undo your last pull, if you didn't yet commit aything new.

Note: 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 rollback to undo your last pull, if you didn't yet commit aything new.

Sharing changes

@@ -336,9 +336,9 @@

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.

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.

Note: 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. We'll cover one of those later.

Note: 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. We'll cover one of those later.

Workflow

@@ -374,7 +374,7 @@

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.

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

@@ -390,9 +390,9 @@ -

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.

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

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

$ hg clone project integration
 $ cd integration
@@ -401,7 +401,7 @@

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

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
@@ -423,15 +423,15 @@
 
 Using a shared repository
 
-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 bundle the changes, send mails and then import the bundles manually. Luckily there's an easier way which works quite well: The shared push repository.
+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 bundle the changes, send mails and then import the bundles 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. Now we use another otion: pushing. As the name suggests it's just the opposite of pulling: You push your changes into another repository.
+Till now we transferred all changes either via email or via pull. Now we use another otion: 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, either on an existing shared server or on a service like BitBucket. Doing so has a bit higher starting cost and takes a bit longer to explain, but it's well worth the effort spent.
+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, either on an existing shared server or on a service like BitBucket. Doing so has a bit higher starting cost and takes a bit longer to explain, but it's well worth the effort spent.
 
-If you want to use an existing shared server, you can use serve there and allow pushing. Also there are some other nice ways to allow pushing to a Mercurial repository, including simple access via SSH.
+If you want to use an existing shared server, you can use serve there and allow pushing. Also there are some other nice ways to allow pushing to a Mercurial repository, including simple access via SSH.
 
 Otherwise you first need to setup a BitBucket Account. Just signup at BitBucket. 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".
 
@@ -441,7 +441,7 @@

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

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

$ hg push https://bitbucket.org/ArneBab/hello/
 
@@ -449,7 +449,7 @@
 
 (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 name and password, then push your code.
+Mercurial will ask for your BitBucket name and password, then push your code.
 
 Voilà, your code is online.
 
@@ -457,11 +457,11 @@
 
 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 usernames of your collegues on the right side under "Permission: Writers". Now they are allowed to push code to the repository.
+After that you can click the "Admin" tab of your created repository and add the usernames 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.
+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
 
@@ -475,15 +475,15 @@

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

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

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.

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.

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.

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

@@ -491,7 +491,7 @@

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.

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 utilized in more complex workflows.

@@ -591,14 +591,14 @@

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.

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 you already have one more revision in your -repository. To remove the bad code, you can just backout of it. This creates a new +repository. To remove the bad code, you can just backout 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.

@@ -650,11 +650,11 @@ -

Now you can commit, pull, push and merge (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.

Now you can commit, pull, push and merge (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.

Merge the named branch

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

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

$ hg update default
 $ hg merge feature1
@@ -695,7 +695,7 @@

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

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
 
@@ -718,13 +718,13 @@
 
 Let's assume you want to get rid of revision 2 and the highest revision is 3.
 
-The first step is to use the "--rev" option to clone: 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
+The first step is to use the "--rev" option to clone: 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
 
 $ 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
+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
@@ -742,7 +742,7 @@
 
 
 
-That's it. hg export also includes the commit message, date, committer and similar metadata, so you are already done.
+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.