comparison hgscm/templates/workflow_guide.html @ 176:f73d4e6949bf

Add index

175:ab2a5f299c2a

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

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

<h1>Basic workflows</h1>

<h2>Log keeping</h2>

<h3>Use Case</h3>

<pre>$ hg log -p -r 3

</pre>

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

<p>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>hg cp</hg> and <hg>hg mv</hg>.</p>

<h2>Seperate 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>But beware, that a rollback itself can't be undone. If you <hg>rollback</hg> and then forget to commit, you can't just say "give me my old commit back". You have to create a new commit.</p>

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

<h2>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>Note: To make this workflow more scaleable, each one of you can have his own BitBucket repository and you can simply <hg>pull</hg> from the others repositories. That way you can easily establish workflows in which certain people act as integrators and finally <hg>push</hg> checked code to a shared pull repository from which all others pull.</p>

<p>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://[e-mail]/path/to/repo. When using a shared directory you just push as if the repository in the shared directory were on your local drive.</p>

<h2>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 <hg>hg help &lt;command&gt;</hg> 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>

</pre>


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

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

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

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

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

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

</pre>

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


<h2>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>That's it. <hg>hg export</hg> also includes the commit message, date, committer and similar metadata, so you are already done.</p>

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

<h2>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 occured.</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>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="quick_start_concepts">basic concept overview</a>.</p>

</div>
<div class="col">
                {% download_button %}
	            {% mercurial_tricks %}
		</div>
	</div>

</div>

176:f73d4e6949bf

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

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

<h2>Log keeping</h2>

<h3>Use Case</h3>

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

<p>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>hg cp</hg> and <hg>hg mv</hg>.</p>

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

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

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

<p>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://[e-mail]/path/to/repo. When using a shared directory you just push as if the repository in the shared directory were on your local drive.</p>

<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 <hg>hg help &lt;command&gt;</hg> 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>

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

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

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

<p>Note: 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>.</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 mark releases, or just mark off revisions as reviewed.</p>

</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>That's it. <hg>hg export</hg> also includes the commit message, date, committer and similar metadata, so you are already done.</p>

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

<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 occured.</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="quick_start_concepts">basic concept overview</a>.</p>

</div>
<div class="col">
        <h2>Index</h2>
        <ul>
            <li><a href="#basic_workflow">Basic workflows</a></li>
            <ul>
                <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>