1. Revision Control with TortoiseHg (Team use) Team usage Prepared by: Steve Teo Contributors: Tong Huu Khiem CS2103 – Software Engineering

2. Slide 2 Sections  Setting up the remote repo on Google Code  Cloning the remote repo  Syncing the local repository with the remote repo  Configuring the username  Pushing changesets  Pulling changesets  Merging changesets  Resolving merge conflict  DRCS workflows

3. Setting up the remote repo on Google Code Step 1

4. Slide 4 Setup a Google Code Repository In this guide, we shall use the excellent open source hosting site Google Code as an example. There are other Mercurial repository-hosting sites such as BitBucket at https://bitbucket.org/, which offers free repositories with various features and restrictions.https://bitbucket.org/ First, sign up for a new project at http://code.google.com/hosting/http://code.google.com/hosting/ Choose Mercurial as your version control system

5. Slide 5 Go to Source tab -> Checkout Remember to note down the repository URL Take note of your repository URL And your password (this is different from your Gmail password) Setup a Google Code Repository

6. Slide 6 You need this password to push changeset to Google Code You can access all the project you have here Setup a Google Code Repository

7. Slide 7 Browse the code in your repository by going to Source tab-> Browse Setup a Google Code repository Files will shows up as you commit code

8. Slide 8 View all the changes in your project by going to Source tab-> Changes A commit graph will shows up as you commit code Setup a Google Code repository

9. Slide 9 Go to the Administer tab -> Sharing and add your team members as owners or committers under Emails of your team members go here Setup a Google Code repository

10. Slide 10 You can configure it to send activity notifications to your Google group (if you set up one for your team) under Administer tab-> Source Add your team’s google group email here Setup a Google Code repository

11. Step 2 Cloning the remote repo

12. Slide 12 If you already have an existing repository of the project on Google Code (set up by one of your team members), you can clone it from the Google Code repository to your hard disk. Otherwise, skip to Step 3skip to Step 3 Right-click on a new folder and select TortoiseHg - Clone Clone a repository

13. Slide 13 Cloning allows you to duplicate the entire repository, copying all the existing contents to the destination as well as the whole revision history. Paste the Google Code repo URL here. This slide explains where to find the Google code repo URL.This slide Clone a repository

14. Step 3 Syncing the local repository with the remote repo

15. Slide 15 If you have an existing local repository, you can also configure it to sync with the repo on Google Code Click Synchronize Sync a local repository with a remote repo

16. Slide 16 Choose https Use the relative URL Use “code.google.com” Use “default” for alias Add the Google Code repository URL as the default path Sync a local repository with a remote repo Save

17. Slide 17 You can also configure Post-Pull behavior for repositories Select Post Pull Update option will make TortoiseHg automatically update your repository whenever you pull some change Sync a local repository with a remote repo

18. Step 4 Configuring the username

19. Slide 19 In a team setting, you need to identify yourself when committing so that you and your teammates know what you committed Configure username for accountability Select a repository and choose Repository Settings

20. Slide 20 Unser Commit group, enter the username & email that you want to associate your commits with Use “name ” here Configure username for accountability

21. Slide 21 You can also set the username in the global settings. If there are no repository-specific settings specified, Mercurial will use the global settings. This affects every repository on your computer Configure username for accountability

22. Slide 22 From now on, your name will show up in subsequent commits This commit username can be different from your Google Code username Commits now have the author which you have just specified Configure username for accountability

23. Step 5 Pushing changesets

24. Slide 24 Pushing changesets Push update your changes from the local repo to a remote repo Member A’s Local Repo Team’s Central Repo push changes A revision is the set of changes whenever a push is performed. Each revision is given a number. A revision is also known as a changeset. In this tutorial, we will use both terms interchangeably. A revision contains other important information such as the author of the changes and the summary of each change. Each successful commit will result in a new revision. Each revision will definitely have one or more revision for its parent except for the first revision, which will have zero.

25. Slide 25 After making some commits to our local repository, we are ready to push all of them into our Central Repository for the first time. Right click on your local repo and choose Hg Workbench Push changesets

26. Slide 26 In Hg Workbench, we will first preview the commits that are to be pushed. Click Detect outgoing changes. This will compare the local and remote repository, finding changes to be pushed Push changesets Click here to preview which changes will be going to the repo

27. Slide 27 These are the changes that is going to be pushed Click Push to upload these to Google Code TortoiseHg will find all the changes that need to be pushed Push changesets

28. Slide 28 Then you will need to authenticate TortoiseHg to reach your Google code repository Enter your Google code username Push changesets

29. Slide 29 And your Google code password, as well. This is not your Google password. This slide explains where to get this password. This slide Push changesets Enter your Google Code password

30. Slide 30 If the commits are pushed successfully, there will be no errors. You can look at the output log for more info in any case. Push changesets Success

31. Slide 31 You can also do a quick verification of the success of your commits by detecting changes for pushing again Push changesets Click here This directly push changes, without checking. Not recommended for now Your commit was pushed

32. Slide 32 Push changesets Go to your Google code repository, check the Source tab-> Changes You should see that your commits were pushed successfully here

33. Slide 33 If you find it a chore to enter your login details every time you push changes or pull from a private repository which you have pull access from, you can store your login details using TortoiseHg. Push changesets Click “Synchronize” to open the sync panel at the bottom Click on the lock to open the security panel Key in your Google account details

34. Step 6 Pulling changesets

35. Slide 35 Update/Merge Pulling changes only retrieves changes from the remote repository into the local repository. However, the working copy is not updated in a Pull operation. You need to update the working copy to the latest version by using the Update command. If there are multiple heads (i.e. same file modified by multiple persons), you need to use the merge command instead. update Member A’s Working Copy Member A’s Local Repo Team’s Central Repo pull changes Update changes

36. Slide 36 Pulling and pushing (Diagram) In the above model, Member A commits some changes and pushes them to the Central Repository. Member A then informs the team to pull his changes off the Central Repository. Member B decides to do so and merges the changes from the Central Repository into his own repository. If any other member wishes to have the latest stable code, all they have to do is to pull off the Central Repository. 36 Member B Member B’s Local Repo Member A Member A’s Local Repo 2. push changes 3. Tells him to pull 1. makes some changes and commit Team’s CentralR epo 4. pull and merge

37. Slide 37 Let’s say Greg have pushed his code. Now his friend, Holly decides to pull the changes into her currently empty local repository. Pull & update changes Again, open Hg Workbench

38. Slide 38 In Hg Workbench, you can check for new changes from repository Pull & update changes Check for changes from Google Code

39. Slide 39 When new changes are detected, you can accept and download them Pull & update changes Click to download changes below

40. Slide 40 The changes have been pulled into the local repository. However, we still need to update the working copy to the latest changes. Pull & update changes This means there are changes that is more up-to-date (2 and 3). You will need to update

41. Slide 41 You can update in Hg Workbench or right-click on the repository and use the popup menu Pull & update changes Click Update to open the update dialog

42. Slide 42 Use the default option to update to the latest changes Pull & update changes

43. Slide 43 Here’s the view after the update. Pull & update changes

44. Slide 44 Finding it so troublesome to pull and then update? You can configure TortoiseHg to update for you by simply configuring the Post-Pull behavior as listed in Step 3: Sync a local repository with a remote repoStep 3: Sync a local repository with a remote repo Summary:  Pulling only pulls the changesets into the local repository.  You still need to update the working copy with the new changesets.  Keep repeating this to yourself: Pull and Update Pull & Update changes

45. Step 7 Merging changesets

46. Slide 46 Merge changesets You may encounter this common scenario Greg pushed his code to the repository. Then Holly & Rowley pulled and updated Greg’s code. Rowley then made some changes, committed and pushed them. Meanwhile, Holly also made her own changes and was about to push the code. This can be summarized in the following timeline

47. Slide 47 Merge changeset Greg Holly Rowley Pushed Pulled & Updated Commit new code Pushed Try to push Commit new code Pulled & Updated time Team Repository (Google Code)

48. Slide 48 In this situation, Holly can’t push. She must merge his changes with Rowley’s This is how Google Code look like after Rowley has pushed his code Merge changesets

49. Slide 49 Here, Holly check her code and detected one changeset that needs to be pushed Merge changesets

50. Slide 50 When she push, however, there was an error. This is because she needs to pull Rowley’s code first Merge changesets

51. Slide 51 Holly proceeds to pull Rowley’s code, seeing one changeset Merge changesets

52. Slide 52 After Holly have pulled Rowley’s code, the repository look like this Now, she need to merge her changes (4) with Rowley’s (5) Merge changesets The newly pulled changeset

53. Slide 53 Holly first select Rowley’s change and proceed with the merge Merge changesets Use Merge with local… to merge the new incoming changesets with yours

54. Slide 54 A summary of the upcoming merge is displayed on the 1 st step of the merging process. Merge changesets

55. Slide 55 Mercurial proceeds to merge and the merge results are shown on the 2 nd step of the merging process. Merge changesets

56. Slide 56 The process of Merging must be finalized with a commit to save the merge on the 3 rd step of the merging process. Merge changesets

57. Slide 57 The merge is done. Holly will now need to push the finalized merge commit back to the repository on Google Code Merge changesets The commit for the merge

58. Slide 58 The merge commit and Holly’s own commits earlier are marked for pushing Merge changesets

59. Slide 59 And then they’re pushed to the remote repository Merge changesets

60. Slide 60 Has this whole section been mind-boggling? Remember, the goal of merging is to combine changes between changesets. Once the merge is complete, it has to be committed and then pushed back to the remote repository. Summary of merging steps :  Pull the incoming changesets from the remote repository  Merge the latest incoming changeset with the local working copy  Commit the merge into the local repository  Push the merge back to the remote repository Find out more about Mercurial’s merging: http://tortoisehg.bitbucket.org/hgbook/1.6/a-tour-of-mercurial-merging- work.html http://tortoisehg.bitbucket.org/hgbook/1.6/a-tour-of-mercurial-merging- work.html Merge changesets

61. Step 8 Resolving merge conflicts

62. Slide 62 The merging scenario which was described in Step 7 is an example of a happy flow. There were no merge conflicts and this should be the case most of the time. In some cases, a merge conflict can result when two people were working on the same file and decided to commit their changes. When Mercurial merges both of their work, it realizes it cannot do so automatically on its own and thus requires intervention from the one who initiated the merge. Merge conflicts are settled by a user selecting which portion of the changed code should be in the ‘merged’ file. Resolve merge conflict

63. Slide 63 Let’s look at a more specific example: Rowley and Holly both started with the same code. Rowley then edited one file, committed and pushed it. At the same time, Holly also edited that file, committed and was about to push it. This creates a situation where Holly need to merge her changeset and Rowley’s, as we have seen in the last section about merging. Normally, if Holly and Rowley change different files, say file A by Rowley and file B by Holly, TortoiseHg will automatically merge, using the newer version of file A from Rowley and a newer version of file B from Holly However, since they both changed one file, TortoiseHg can’t figure out whose version to use. This situation causes a merge conflict Resolve merge conflict

64. Slide 64 Merge changeset Rowley Holly Pulled & Updated Commit new code Pushed Try to push Commit new code Pulled & Updated time One file, project.txt for example Create version A of project.txt Create version B of project.txt

65. Slide 65 In this real example, Rowley and Holly started from Holly’s version of the code, where she add Stylizer.h and Stylizer.cpp Resolve merge conflict They both started from this revision

66. Slide 66 Both Rowley and Holly decides to edit these files in their own way Resolve merge conflict Stylizer.h Stylizer.cpp Added a function called Stylize [Stylizer.h], add: void Stylize(fstream one_file); [Stylizer.cpp], add: void Stylizer::Stylize(fstream one_file) { }; Added a function called Style_file [Stylizer.h], add: void Style_file(fstream one_file); [Stylizer.cpp], add: void Stylizer::Style_file (fstream one_file) { };

67. Slide 67 Holly has edited the file and pushed her changeset to Google Code Resolve merge conflict Holly’s new changeset

68. Slide 68 While pushing his commit, Rowley got an error Then he proceeds to do a pull Resolve merge conflict

69. Slide 69 After Rowley pulled, he saw that Holly have one changeset that he doesn’t Now he need to merge his change with Holly’s Resolve merge conflict The changeset Rowley pulled

70. Slide 70 Again, this is done using the Merge with local option Resolve merge conflict Use Merge with local… to merge the new incoming changesets with yours

71. Slide 71 A dialog box shows up, summarizing the upcoming merge Resolve merge conflict

72. Slide 72 However, a conflict showed up while merging Rowley now need to resolve this before continuing Resolve merge conflict Click here to resolve the merge conflict

73. Slide 73 The Resolve conflicts dialog shows up Resolve merge conflict Actions: Mercurial Resolve – Let Mercurial resolve it automatically (trivial) Tool Resolve – Let the default merge tool resolve it Take Local – Takes the version of the file in local working copy. Take Other – Take the other version of the file which is not the local working copy. Mark as Resolved – Marks the file as resolved

74. Slide 74 For example, if you use Tool Resolve, TortoiseHg will launch kidff3 and you can resolve the conflict there Resolve merge conflict Click A and/or B and/or C here to indicate which version(s) you want to have in the merged file. This shows what you’ll have in the merged file

75. Slide 75 After all conflicts are resolved, close the dialog box and commit the merge, similar to Step 7: Merge changeset7: Merge changeset Resolve merge conflict

76. Slide 76 And this is how it is in Google code repository Resolve merge conflict The conflicted merge

77. Slide 77 The example above was the resolution of a simple merge conflict. Even though Rowley and Holly edited the same file, their changes were on different lines. Mercurial or the default Diff program was smart enough to resolve it automatically on its own. Therefore, Rowley did not need to choose which changes he wanted. In other complex cases, you and your team mates could have edited the same section of code. In those cases, you have to use the Diff program to select which sections of code you want in the final merged code. Resolving merge conflicts

78. DRCS workflows

79. Slide 79 An example scenario Membe r B Member B’s Local Repo Membe r A Member A’s Local Repo Memb er A’s Hosted Repo 1. pull and merge 3. push changes 4. sends pull request 2. makes some changes and commit Memb er B’s Hosted Repo 5. pull and merge 6. push changes You can see that Member A pulls the latest changes off Member B’s remote repo and merges the changes with his local repo. Now that his local repository is updated, he then commits his own changes and pushes them to his hosted repository. Member A then informs the team to pull his changes off his hosted repository. Member B decides to do so and merges the changes from Member A’s hosted repository into his own local repository. Each of the members does not pull off from one another’s local repository. Instead, they pull off changes from one another’s hosted repository.