Editing Mercurial

Jump to navigation Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.

Latest revision Your text
Line 2: Line 2:


Everybody is free to '''run, copy, distribute, study, change and improve'''<ref>https://www.gnu.org/philosophy/free-sw.en.html</ref> Octave's source code, given in the main repository at https://www.octave.org/hg/octave.  Use Mercurial to get the latest version of Octave <pre>hg clone https://www.octave.org/hg/octave</pre>
Everybody is free to '''run, copy, distribute, study, change and improve'''<ref>https://www.gnu.org/philosophy/free-sw.en.html</ref> Octave's source code, given in the main repository at https://www.octave.org/hg/octave.  Use Mercurial to get the latest version of Octave <pre>hg clone https://www.octave.org/hg/octave</pre>
== Workflow reference ==
This section gives several frequently used Mercurial commands and sequences.
* Initial clone: <pre>hg clone https://hg.savannah.gnu.org/hgweb/octave/</pre>
You can then bootstrap, configure and make, make check, maybe make install.
* To update on a regular basis, you can do <pre>hg pull -u</pre> or <pre>hg pull && hg up</pre>
* To make a ''local clone'', you can clone from your main Octave repository on your computer to another directory like this: <pre>hg clone octave myfeature</pre> which will clone the Octave directory into a new directory called "myfeature". You'll need to cd to the correct directory first. Then you can cd into the new directory and run bootstrap, configure, make. To prevent a fresh download of gnulib, you can specify the path to the first Octave directory's gnulib if you want.
It is best practice to make a new clone directory for each feature or bugfix you work on, which makes recovery from mistakes much easier.
* To work on the stable branch instead of the default branch, make a local clone called "stable", then cd to it and <pre>hg update stable</pre>
* To circulate work-in-progress bugfixes: first cd to the relevant local clone, then edit the relevant files, verify that it builds, then <pre>hg diff &gt;/tmp/my.wip.patch</pre> and then upload that file to the bug tracker discussion. You can also copy-paste it into a bug discussion using ''verbatim'' tags if the patch is small enough. Accept feedback from the bug discussion and iterate your patch.
* When you're ready to commit your fix, first pull and update your main Octave directory from Savannah, then pull and update your local clones. Then build again to make sure things haven't broken. Then <pre>hg commit</pre> and type a summary and context for your change. Exit the editor, saving when it prompts. Build again so your build gets the latest hg id. Type <pre>hg export &gt;/tmp/my.patch</pre> and upload that file into the bug discussion. Wait for a maintainer to apply it with your name, then if you do <pre>hg in</pre> in your main Octave directory it'll show up as an incoming change. Do a pull and up to get that, then do a pull and up in your individual clone directories to get it there.
* To merge changes from stable to default <pre>hg merge stable</pre>. It's best to run this only in local clones that are already on the default branch. That way, local clones on stable don't have to switch branches before merging.
* To push to a repository, if you have push rights to that repository, you can see what's going out with <pre>hg out</pre> and then if you're happy with it you can<pre>hg push</pre>.
==Tutorials==
Joel Spolsky's Mercurial tutorial: [https://hginit.github.io/01.html https://hginit.github.io/01.html]


{{Note|[https://tortoisehg.bitbucket.io/ TortoiseHg] is a GUI for Mercurial and it is especially recommended for users doing their first steps with source code management systems.  Linux, macOS, and MS Windows are supported.}}
{{Note|[https://tortoisehg.bitbucket.io/ TortoiseHg] is a GUI for Mercurial and it is especially recommended for users doing their first steps with source code management systems.  Linux, macOS, and MS Windows are supported.}}
Line 47: Line 21:
# Node ID 68c698c4f2fd98bf2d48234bd1da99e91763114f
# Node ID 68c698c4f2fd98bf2d48234bd1da99e91763114f
# Parent  f5c9bb5955e7c9fddef5c3c3f115201e11b43b79
# Parent  f5c9bb5955e7c9fddef5c3c3f115201e11b43b79
help.m: Display relevant topics first (bug #42424)
help.m: Display relevant topics first (bug #42424)


Line 110: Line 83:
#* Do not mention backed-out commits.
#* Do not mention backed-out commits.
# Prepare a singe patch (changeset) including all code that should be submitted for review <syntaxhighlight lang="bash">
# Prepare a singe patch (changeset) including all code that should be submitted for review <syntaxhighlight lang="bash">
hg pull https://www.octave.org/hg/octave   # Get remote "tip" and "@"
hg pull https://www.octave.org/hg/octave
hg update -r @                             # Activate    bookmark "@"
hg update -r @
hg merge my-gsoc                           # Merge "my-gsoc" into "@"
hg merge my-gsoc
hg commit
hg commit
hg export -r tip -o mid-term-review.patch
hg export tip > mid-term-review.patch
</syntaxhighlight> The file {{Path|mid-term-review.patch}} can uploaded to the [https://savannah.gnu.org/patch/?group=octave patch tracker]. <br/> Finally, there is a subtle difference between <code>"tip"</code>, which is a reference to the (local or remote) changeset added to the repository most recently and the bookmark <code>"@"</code> used by the Octave developers to point to the latest remote changeset.  Often both refer to the very same changeset and they can used interchangeably.
</syntaxhighlight> The file {{Path|mid-term-review.patch}} can uploaded to the [https://savannah.gnu.org/patch/?group=octave patch tracker].


== Example Mercurial configuration ==
== Example Mercurial configuration ==
Line 176: Line 149:
[alias]
[alias]
glog = log --graph
glog = log --graph
top = log --graph -l
top = log --graph -l
</syntaxhighlight>}}
</syntaxhighlight>}}
== Tips for working with TortoiseHg ==
TortoiseHg is a multi-platform graphical user interface for Mercurial repositories. It allows to perform many hg operations using the context menu and toolbar buttons. That might make it easier to get used to working with Mercurial.
=== Activate the "mq" extension ===
The "mq" extension allows to modify (local) changesets after they have been committed. It also allows to rebase changes to a new parent or to strip changes completely.
The "mq" extension does *not* allow to modify pushed changes.
To activate the "mq" extension in TortoiseSVN, open the settings, select "Extensions" on the global settings tab and activate the checkbox next to "mq".
The most useful feature of that extension is probably to update an existing changeset. For this, select "Modify History" -> "Import to MQ" in the right click menu of the respective changeset. After updating some local files or changing the commit message, hit the "QRefresh" button. Finish the patch by selecting "Modify History" -> "Finish Patch" from the right click menu of the respective changeset.
=== Rebase a change to a current tip ===
Sometimes a change in the upstream repository might make it necessary to rebase a changeset to a new parent. There are several ways to achieve this. The ways described here might not be the most elegant ones. Any editor is welcome to add onto this.
Strip and commit:
# Pull changes from the upstream repository.
# Before updating to the new tip, strip the local changes by selecting "Modify History" -> "Strip..." from the right click menu. In the dialog, select "Do not modify working copy during strip (-k/--keep)".
# Update to the new tip (maybe in incremental steps).
# Commit the local changes in a "fresh" changeset. This has the drawback that any commit message might be lost. But it often works even if other approaches fail.
Un-apply and re-apply:
# Pull changes from the upstream repository.
# Before updating to the new tip, import the local changeset to mq by selecting "Modify History" -> "Import to MQ" in the right click menu.
# You might want to refresh the changeset with local changes.
# Un-apply the patch by selecting "Modify History" -> "Unapply Patch" from the right click menu. If there are other, un-committed changes in the local repository, you might want to select "Tolerate non-conflicting local changes (--keep-changes)" in the "Modify History" -> "MQ Options" dialog from the right click menu beforehand.
# Update to the new tip.
# Select the previously unapplied patch on top of the revision graph and re-apply it by using the "Reapply Patch" option in the right click menu. This has the advantage that a commit message will be retained. But re-applying the patch might fail if there were changes in the upstream repository that made the patch incompatible.
Rebase:
# Pull changes from the upstream repository.
# Select the local changeset that you'd like to rebase.
# Hold down the Ctrl key and select the changeset that should be the new parent of the local changeset (probably the new tip).
# Right-click the changeset of the new parent and select "Rebase...".
# The default settings are often times fine. This process has the advantage that a commit message will be retained and it often times resolves conflicts automatically. But it doesn't work if there are any un-committed local changes.


== Footnotes ==
== Footnotes ==
Please note that all contributions to Octave may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see Octave:Copyrights for details). Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel Editing help (opens in new window)

Templates used on this page:

Retrieved from "https://wiki.octave.org/Mercurial"