| smf |
The 'Guide' web page has stale references to bitbucket. The attached patch against the hg-website repo takes a pass at an update.
Remove stale bitbucket refs. Some spelling updates. BitBucket dropped support for mercurial repos in 2020. Fix stale references to it in favor of more generic language about other hosting services (and point to a curated list on the wiki).
Added smf (current website repo meister)
See also issue 6518
| Lint Skipped |
| Unit Tests Skipped |
| <ul> | <ul> | ||||
| <li> <a title="Mercurial Tutorial" href="https://www.mercurial-scm.org/wiki/Tutorial">Tutorial</a> - a more exhaustive tutorial. </li> | <li> <a title="Mercurial Tutorial" href="https://www.mercurial-scm.org/wiki/Tutorial">Tutorial</a> - a more exhaustive tutorial. </li> | ||||
| <li><a title="Mercurial: The definitive Guide" href="https://book.mercurial-scm.org/">Mercurial: The Definitive Guide</a> - a very detailed description of Mercurial including <a title="Behind the Scenes" href="https://book.mercurial-scm.org/read/concepts.html">behind the scenes</a>, an indepth article on the design of Mercurial.</li> | <li><a title="Mercurial: The definitive Guide" href="https://book.mercurial-scm.org/">Mercurial: The Definitive Guide</a> - a very detailed description of Mercurial including <a title="Behind the Scenes" href="https://book.mercurial-scm.org/read/concepts.html">behind the scenes</a>, an in-depth article on the design of Mercurial.</li> | ||||
| <li><a title="Understanding Mercurial" href="https://www.mercurial-scm.org/wiki/UnderstandingMercurial">Understanding Mercurial</a> - the concepts behind Mercurial.</li> | <li><a title="Understanding Mercurial" href="https://www.mercurial-scm.org/wiki/UnderstandingMercurial">Understanding Mercurial</a> - the concepts behind Mercurial.</li> | ||||
| </ul> | </ul> | ||||
| <p>The second workflow is still very easy: You're a lone developer and you want to use Mercurial to <strong>keep track of your own changes</strong> and <strong>optimize your workflow</strong>.</p> | <p>The second workflow is still very easy: You're a lone developer and you want to use Mercurial to <strong>keep track of your own changes</strong> and <strong>optimize your workflow</strong>.</p> | ||||
| <p>It works just like the log keeping workflow, with the difference that you go back to earlier changes at times and work onwards from there.</p> | <p>It works just like the log keeping workflow, with the difference that you go back to earlier changes at times and work onward from there.</p> | ||||
| <p>To start a new project, you initialize a repository, add your files and commit whenever you finished a part of your work.</p> | <p>To start a new project, you initialize a repository, add your files and commit whenever you finished a part of your work.</p> | ||||
| <div class="note"> | <div class="note"> | ||||
| <p class="note-title">Note:</p> | <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="https://www.mercurial-scm.org/wiki/UnderstandingMercurial">basic concepts</a>]. When you're at the most recent revision, <em>hg identify -n</em> will return "-1". | <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 Mercurial's [<a href="https://www.mercurial-scm.org/wiki/UnderstandingMercurial">basic concepts</a>]. When you're at the most recent revision, <em>hg identify -n</em> will return "-1". | ||||
| </div> | </div> | ||||
| <p>To update to the most recent revision, you can use "tip" as revision name.</p> | <p>To update to the most recent revision, you can use "tip" as revision name.</p> | ||||
| <p>The basic requirement for that is that you have to be able to see the changes of others.</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> | <p>Mercurial allows you to do that very easily by including a simple web server from which you can <em>pull</em> changes just as you can pull changes from local clones.</p> | ||||
| <div class="note"> | <div class="note"> | ||||
| <p class="note-title">Note:</p> | <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. | There are a few other ways to share changes, though. Instead of using the builtin web server, 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> | </div> | ||||
| <h3>Workflow</h3> | <h3>Workflow</h3> | ||||
| <h5>Using the builtin webserver</h5> | <h5>Using the builtin web server</h5> | ||||
| <p>This is the easiest way to quickly share changes.</p> | <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> | <p>First the one who wants to share his changes creates the web server</p> | ||||
| <pre>$ hg serve | <pre>$ hg serve | ||||
| <h5>Sending changes by email</h5> | <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>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 time zones. 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>In that case, you can easily export your changes as patches and send them by email.</p> | ||||
| <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>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>Until 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>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>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 time zones, so we'll go with another approach here: Using a shared repository, either on an existing shared server or on a service. Doing so can have 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="https://www.mercurial-scm.org/wiki/PublishingRepositories#Allowing_push">allow pushing</a>. Also there are some other nice ways to <a title="Multiple Committers" href="https://www.mercurial-scm.org/wiki/MultipleCommitters">allow pushing to a Mercurial repository</a>, including simple <a title="Setting up a shared Mercurial repository using SSH" href="https://www.mercurial-scm.org/wiki/SharedSSH">access via SSH</a>.</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="https://www.mercurial-scm.org/wiki/PublishingRepositories#Allowing_push">allow pushing</a>. Also there are some other nice ways to <a title="Multiple Committers" href="https://www.mercurial-scm.org/wiki/MultipleCommitters">allow pushing to a Mercurial repository</a>, including simple <a title="Setting up a shared Mercurial repository using SSH" href="https://www.mercurial-scm.org/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>If you want to use an existing repository sharing service that supports Mercurial, there are a number of <a title="Mercurial public or private hosting options" href="https://www.mercurial-scm.org/wiki/MercurialHosting">publicly hosted services or self-hosted options</a>. | ||||
| <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/ | <p>To see what you would get if you would push to a shared repository, you can use <em>outgoing</em>. It works with local repositories in the same way as with shared ones, so you can test it with a local one:</p> | ||||
| </pre> | |||||
| <p>(Replace the URL with the URL of your created repository. If your username is "Foo" and your repository is named "bar", the URL will be https://bitbucket.org/Foo/bar/)</p> | |||||
| <p>Mercurial will ask for your BitBucket name and password, then <em>push</em> your code.</p> | |||||
| <p>Voilà, your code is online.</p> | |||||
| <p>To see what you would get if you would push, you can use outgoing. It works with local repositories in the same way as with shared ones, so you can test it with a local one:</p> | |||||
| <pre>$ hg outgoing ../feature1 | <pre>$ hg outgoing ../feature1 | ||||
| </pre> | </pre> | ||||
| <div class="output">output of hg outgoing ../feature1 (our feature seperation repo): | <div class="output">output of hg outgoing ../feature1 (our feature separation repo): | ||||
| comparing with ../feature1 | comparing with ../feature1 | ||||
| searching for changes | searching for changes | ||||
| changeset: 6:3f549b33c7ef | changeset: 6:3f549b33c7ef | ||||
| <div class="note"> | <div class="note"> | ||||
| <p class="note-title">Note:</p> | <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>. | You can often use SSH for pushing to and pulling from publicly hosted shared repository services. | ||||
| </div> | </div> | ||||
| <p>Now it's time to tell all your colleagues to sign up at BitBucket, too.</p> | <p>When you clone a remote repository to a local repository, it will automatically be configured to pull/push from/to the remote repository, so new contributors can just use <em>hg push</em> and <em>hg pull</em> without an URL.</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"> | <div class="note"> | ||||
| <p class="note-title">Note:</p> | <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. | You can also use this workflow with a self-hosted shared server instead of a public repository hosting service, either via SSH or via a directory that is shared between users on a private network (e.g., NFS or other network file sharing mechanisms). 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. Consult the <a title="URL Paths" href="https://www.mercurial-scm.org/doc/hg.1.html#url-paths">URL Paths documentation</a> (<em>hg help urls</em>) for more information on specifying a path to a shared repository. | ||||
| </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> | </div> | ||||
| <h2 id="basic_summary">Summary</h2> | <h2 id="basic_summary">Summary</h2> | ||||
| </pre> | </pre> | ||||
| <h3>share your repository via the integrated webserver</h3> | <h3>share your repository via the integrated web server</h3> | ||||
| <pre>$ hg serve & | <pre>$ hg serve & | ||||
| $ cd .. | $ cd .. | ||||
| </pre> | </pre> | ||||
| <h3>Use shared repositories on BitBucket</h3> | <h3>Use shared repositories on a public repository sharing service</h3> | ||||
| <pre>$ (setup bitbucket repo) | <pre>$ (setup repo as documented by the service) | ||||
| $ hg push https://bitbucket.org/USER/REPO | $ hg push https://example.org/USER/REPO | ||||
| (enter name and password in the prompt) | (depending on the service, you might be prompted for username and password, and the exact URL will be different than this example) | ||||
| $ hg pull https://bitbucket.org/USER/REPO | $ hg pull https://example.org/USER/REPO | ||||
| </pre> | </pre> | ||||