Revision Control with TortoiseHg

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

2. Before we begin… Red, bold text are important things. Notesclarify things and provides more in-depth knowledge These gray boxes have notes inside These instructionsis tested with version 2.4.2 of TortoiseHg Red box means instructions.Follow them. Except the titles, of course 

3. Moving on from individual use… • Version control is important for an individual developer. • Regularrevision controlhelps a developer manage his/her code, increasing productivity. • The Mercurial Revision Control System offers the advantage of having a local repository • With a local repository, commits and other repository operations can be done offline at any time. • Developers, especially those who have used RCSs such as Subversion (which lacks the local repository feature), will find regular versioning with Mercurial a joy, not chore. • However, you have yet to fully utilize the capabilities of a Revision Control System if you’re using it alone.

4. … to team use of a RCS • RCS is used to manage the codebase of software development projects (which consists of teams of developers) in the industry, making it crucialto learn how to use it properly now. • The Mercurial Revision Control System is fully capable of supporting team projects. • Adopting a RCS for team use requires the establishment of a workflow and making sure team members follow it. • In this first part, we shall learn a workflow to get a good grasp of it before proceeding with the practical itself.

5. Objectives • Learn the Central Repository Model • Role of the team’s centralized repository • Basic team workflow • Putting everything into practice • Setup a Google Code Repository • Checkout a remote repository • Sync a local repository with a remote repo • Configure username for identity purpose • Push changesets • Pull-Update changesets • Merge changesets • Resolve merge conflict • Unleash Mercurial’s full power

6. Central Repository Model

7. The missing link • Every team member will have their own local repository. However, there is no mechanism yet to share code changes with one another. Team Leader’s Local Repo Member A’s Local Repo Team Leader Member A Member C’s Local Repo Member B’s Local Repo Member C Member B

8. Central Repository Model • In the Central Repository Model, there is a central (remote) repository owned by the team • Team members download (‘pull’) and upload (‘push’) changes between their own local repositories and the central repository. • A team member’s local repository cannot sharechanges directly with other members’ local repositories. • Developers can choose to push their changes to the central repository only when they are confident of their changes. • Thus, it is not guaranteed that the central repository will always have the latest code. • However, it is expected to contain the latest stable code.

9. Central Repository Model Team’s Central Repo Leader’s Local Repo Member A’s Local Repo Team Leader Member A Member C’s Local Repo Member B’s Local Repo Member C Member B

10. Basic team workflow

11. Push • Update your changes from the local repo to a remote repo pushchanges Team’s Central Repo Member A’s Local Repo

12. Revision/changeset • A revisionis the set of changes whenever a push is performed. Each revision is given a number. A revisionis 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.

13. Pull • Retrieve new changes from the remote repo to your local repo pullchanges Team’s Central Repo Member A’s Local Repo

14. 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 Updatecommand. If there are multiple heads (i.e. same file modified by multiple persons), you need to use the merge command instead. Member A’s Local Repo Member A’s Working Copy update

15. Pull+update? • There are a few ways of doing a pull and update in one shot. • In Step 3 of “Putting everything into practice”, we will show you how you can set up such behavior using TortoiseHg itself. • For the command line gurus, you can use the hg fetch command to do pull and update in one shot (need to enable the fetch extension first).

16. Pulling and pushing (Diagram) Member B’s Local Repo Member B Team’s CentralRepo 4. pulland merge 3. Tells him to pull Member A’s Local Repo Member A 2. pushchanges 1. makes some changes and commit

17. Pulling & pushing (explanation) • 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.

18. Putting everything to practice

19. Step 1 Setup a Google Code Repository

20. Setup a Google Code Repository • In this guide, we shall use the excellent open source hosting site Google Code as an example. However, note that your code will be available for checkout by anyone. • There are other Mercurial repository-hosting sites such as BitBucket athttps://bitbucket.org/, which offers free private repositories as long as access to the repository is kept to 5 users. Note for CS2103/T students: Your project tutor will set up the Google Code account for you. Instructions under step 1 are for your information only. But you should follow from Step 2 onwards.

21. Setup a Google Code Repository Sign up for a new project athttp://code.google.com/hosting/ Choose Mercurial as your version control system

22. Setup a Google Code Repository Go to Sourcetab -> Checkout Remember to note downthe repository URL Take note of your repository URL Access your password

23. Setup a Google Code Repository Rememberof your googlecode.com password, too You need this password to push changeset to Google Code You can access all the project you have here

24. Setup a Google Code repository Browse the code in your repository by going to Sourcetab-> Browse Files will shows up as you commit code

25. Setup a Google Code repository View all the changes in your project by going to Sourcetab-> Browse A commit graph will shows up as you commit code

26. Setup a Google Code repository Add your team members as Ownersunder the Administertab -> Sharing Emails of your team members go here

27. Setup a Google Code repository Remember to create a Google group for your team and add it to the activity notification under Administertab-> Source Add your team’s google group email here

28. Step 2 Clone a repository

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

30. Clone a repository Cloningallows 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.

31. Step 3 Sync a local repositorywith a remote repo

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

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

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

35. Step 4 Configure username for accountability

36. Configure username for accountability In a team setting, you need to establish an identityso that you and your teammates know what you guys committed Select a repository and choose Repository Settings

37. Configure username for accountability Unser Commitgroup, enter the username & email that you want to associate your commits with Use “name <email>” here

38. Configure username for accountability 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

39. Configure username for accountability 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

40. Step 5 Push changeset

41. Push changesets 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

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

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

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

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

46. Push changesets If the commits are pushed successfully, there will be no errors. You can look at the output logfor more info in any case. Success 

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

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

49. Push changesets 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 detailsusing TortoiseHg. Click “Synchronize” to open the sync panel at the bottom Click on the lock to openthe security panel Key in your Google account details

50. Step 6 Pull & Update changeset