Using TortoiseHG (GUI) - Working with branches - Creating Pull Request

[Audionut]

Being a dumb windows user, I like GUI's.  Turns out there is a frontend already installed in the pre-built VM.

Note:  Windows and Mac users, may be interested in the free GUI from Atlassian, the owners of bitbucket.

You will find it in the ubuntu menu under development.

TortoiseHG


There are a couple of things to setup beforehand that will increase the usability.
TortoiseHG needs a visualdiff tool which is used to compare 2 file revisions, and easily patch between them.  The first one I found was Meld.  This can be installed in the VM by using the Ubuntu Software Center, found in the Ubuntu menu.

So lets create a new repository in TortoiseHG and clone the ML repository.
Select the file menu and create new repository.



In the options panel that appears, select a location on the local drive to create the repository and click create.



This creates a blank repository on the local drive like so.


From here, it's best to set a couple of settings in TortoiseHG.  Select the file menu and settings.


This will allow us to perform some functions at a later date.  The text in the visual editor option.

Code Select Expand

emacs [+$LINENUM $FILE] [--eval '(highlight-regexp "$SEARCH")']

I use emacs for this tutorial.  And this can be installed via the ubuntu software manager also.  If you are more proficient with linux, you can use any editor you wish.

Now, we need to clone the ML repository to the local drive.

• Select the synchronise panel
• Change the location from local to https
• Enter the web address for the ML repo
• Hit the pull button

The ML source and all the changesets will now be on the local drive.  However, you need update the unified branch to HEAD, which will also push the files to your local repository.

• Scroll through the commit log and find the first entry for the Unified branch
• Right click on the commit and select Update...

Now you can browse the files in your local repository, and start building the source.  Right click on the repository and choose the option.

[Audionut]

From here, it's best to create your own branch.  This will ensure that any changes you make are to your own branch, and you do not edit the files in the main UNIFIED branch.  So if you make a mistake, you don't need to clone the entire repository again, you can just update the unified branch to HEAD, create a new branch, and continue just like you are editing a fresh repo.

See this post by dmilligan: http://www.magiclantern.fm/forum/index.php?topic=9524.0

• Select the commit panel
• Click on Branch: default
• Select Open a new named branch, and give your branch a name

Lets commit the changes.

• Enter a commit message
• Hit the commit button
• Create branch

Note:  You can edit files before creating a branch.  This way your commit log doesn't contain a commit solely just for a new branch.  Instead, the new branch will be created as you commit your changes.

The changes are reflected in the commit log.



Lets merge some of the other branches with our local repo.  For this tutorial, I'll be working with the 5D3.123 branch.

• Scroll* through the commit log and find the first entry for the branch
• Right click on the commit and select Merge with Local...

* Or as a1ex points out below, you can select the loupe which opens the filter toolbar.

• The loupe
• Filter by changeset type
• Filter by branch

A quick summary appears, click next*


* Enabling the option to automatically resolve merge conflicts seems to fix some weird conflict messages.



And a summary of the merge.



There are some conflicts between the branch we are merging (5D3.123) and the local repository.  Click on the resolved.
Here we have a summary of the conflicting files.


With all files selected, lets click Tool Resolve.
This moves the files to the Resolved conflicts panel, and we can resolve each file.



Select a file to resolve, and select Diff to other.
This will automatically open the Meld diff tool.



From the changes menu (1), you can push and pull changes as needed.
If there are other conflicts in the file, you can select the down arrow (2) which will show you the next conflict in the file.
After all conflicts have been resolved, you might be greeted with this.



Success!
Click save (3) and close Meld.

When you have resolved all conflicts, click close.


This takes us back to the merge summary, and we can now click next.
We end up at the commit summary.



We can change the commit message if wanted, and click commit.
A final summary appears, we can click finish.
The result is reflected in the commit log.

[Audionut]

This will focus on the process of creating a pull request.  There are some option that can be set in tortoiseHG to make the process a little easier, and I will update this tutorial at a later date.

The first thing you should do is fork the repository.
And make a note of the web address to your fork.


Lets move on to editing a file, pushing it from our local repository to our online repository, and creating a pull request.

• Select the manifest panel
• Browse to the file to be edited
• Right click and select edit local

Note:  You don't have to edit the file in this way.  You can edit the file however is easiest for yourself.

When the file has been edited and saved, return to TortoiseHG.

• Select the commit panel
• Click the refresh button to refresh the list of edited files
• The list of edited files
• Enter a commit message
• Create a new branch if needed for your pull request
• A summary of the changes to the file
• Press commit

Notes:

You do not have to edit each file and commit it in a singular fashion.  You can edit as many files as you like, and then return to committing them all.  You simply check the files that you want included in each commit, commit them, select the next file to commit, commit it, and so on.

However, I don't believe that TortoiseHG can commit multiple changes to a file as separate commits.  In other words, if you edit a file for multiple reasons, you should commit each edit to the file as needed.

The Magic Lantern development team requires all commits to contain only the changes, for that commit.

Commit messages should be as descriptive as possible, with the least amount of characters.
"Change underexpose zebras to around -9EV"  <-- This is short and descriptive
"Edited zebras.c"  <--  Bonus points for a short commit message, fail for bring non descriptive.

Now lets push the changes from our local repository, to our online repository.

• Select the synchronisation panel
• Change the web address to your online repository you forked earlier
• Push the changes

Select yes at the next prompt to start pushing the changes.

Select yes to create the new branch at our online repository.


Enter the password you use to login at bitbucket.


When it has completed, the changes should be reflected in your online repository.


Note: This commit contained the merge of the 5D3.123 branch.  This cannot be separated in the pull request.  I updated the unified branch to HEAD, made the file changes, committed them, and push them to the online repository.

Lets create a pull request.

• Select Pull Request
• Select the branch containing the changes you want to commit
• Change the pull request title if neeeded
• Add a description
• Close the branch after the pull request has been merged
• Check to make sure the pull request only contains the commits needed
• Create the pull request

*Note:  You can also submit pull requests to branches in ML.  See this post.

With the pull request created, it will end up in the Magic Lantern repository for approval by the development team.

[Audionut]

I had to hunt around online, to work out what line to put into the TortiseHG settings, to open an editor, for editing files.

The only thing I found was a guide for emacs.  I would really prefer to use something simple like leafpad. 
Does anyone know the correct syntax to make TortoiseHG use leafpad instead?

[a1ex]

Wow, nice tutorial! This made me actually try tortoisehg (I was using hgview + qct + command line).

First tip: the filter toolbar is hidden by default. Click on the loupe and you can choose the branches from a drop-down list (much faster than scrolling around).

First surprise: where did the merging conflicts came from? I did check if 5D3-123 merges cleanly with unified and iso-research last night...

Turns out, command-line hg auto-resolves simple conflicts (which I didn't even regard as conflicts). Enabled "Auto-resolve merges" and... no more conflicts!

[Audionut]

It looks like it might be conflicting some file changes in the branch being merged, with some sort of old local file copy.  Not really sure.
But some of these so called conflicts, certainly shouldn't be classed as such.

Thanks for the extra tips.

You can right click on a commit and export a patch, backout the changeset, etc, etc.

[thebeagle]

I work at a place that has hundreds of branches in hg. The only way I know of to access them in tortoisehg (or hgview for that matter) is through the dropdown  or the 'loop' search tool. The loop search tool is good if you know the name of the branch you want, but sometimes I don't know the exact name and it would be nice to be able to browse the list of branches. Does anyone know a good way to do that?

Scrolling through the dropdown is way too slow when there are hundreds/thousands of branches.  The dropdown allows the user to type in the name but you have to be fast and accurate with your typing as it cuts you off if you type too slow (it's an infuriating sport to try your hand at!) If you click outside of the dropdown you have to start your search all over.

I just discovered that I can use the 'page up' and 'page down' keys on my keyboard to kind of fast forward through the dropdown. That helps. Any other tips for this dilemma?

[Audionut]

You can submit your pull requests to branches in ML.  Select the required branch in the marked box.

[Audionut]

With the new bitbucket UI, there doesn't appear to be a way to sync your forks.  edit:  Found the option.

Also, after creating a pull request, when you push changes to your fork (in the same branch), the pull request gets automatically updated.  This may be useful, or, not so useful, depending on your proficiency.

edit:  https://bitbucket.org/site/master/issue/5231/pull-requests-should-update-with-newest

[ravibharath]

Hi All,

I am new to TortoiseHg Workbench. I have updated one file in a branch called A and committed it. I would like to have this update alone (not others) in another branch called B. Is it possible in Tortoisehg GUI?


Thanks
Ravi

[dmilligan]

Easiest way would be to export that one change as a patch, and then switch branches and apply the patch.