Using Tortoise Hg
From RoboWiki
Tortoise Hg (Mercurial) is a source code version control system. It allows multiple users to copy source code from a repository (where the central, working project is stored) onto their own computer. Users can then edit the code on their computer and, once they have created an updated and working version of the project, upload it back to the original repository.
Contents |
Creating the Parent Repository
The parent repository is where final, working versions of a code or project will be stored by users. It is also the repository that all users working on the project will submit their changes too, and receive changes from other users.
The location of the parent repository should be on a server where multiple users can access it. In robotics, we use the draft server as our location for the parent repository.
1) Find a location for the parent repository. All users working on the project should be able to access it.
2) Create a folder for the repository. The name of the repository should let others browsing the file system know that a) This folder is a repository, and b) what is in the repository. For example, "DSRepo" would be a name which tells us that the folder contains a repository for DS programming.
3) Inside the folder, right-click the empty space. Hover the mouse over "TortoiseHg" and a menu should show up. Click on "Create Repository Here". Keep the default settings, and press "Create."
Now there will be a ".hg" folder. Do not modify this folder in any way. Instead, create another folder in the directory called 'Files'. In here you can store everything you wish to distribute. Start by creating a text file inside 'Files' called "READ ME". You can choose to edit this file or leave it blank. The purpose of this file is to allow us to "commit" changes when the real project has not yet begun.
Cloning a Repository
When you want to work on a project that others are working on, you need to download the parent repository to your own computer. This is called cloning. First, you must create a folder to contain the child repository. Inside the folder, right-click the empty space. Hover over "TortoiseHg" and click "Clone..." from the menu.
You will be asked for the source path and the destination path. The destination path should be the folder you are already in (the one where the parent repository will be copied to). The source path is the folder where the parent repository is located. This may be on your own computer or an a server. If the parent repository is on your computer, just navigate to the folder using "Browse.." If the repository is located on a server (such as our Draftserver), you'll need to manually type the location of the server, such as: "\\ServerName\MainRepo". Now, press "Clone". Once the clone is finished, the clone program will close and the ".hg" folder should appear in the cloned repo folder.
Commit, Push, and Pull
Commit is used whenever you want to create an update. It finds new files added and any changes made to existing files. Empty folders will not be copied. Push is used to send the update created in 'commit' to the parent repository. Pull is used to take updates to the parent repository from other users and put them in your child repository.
Creating an update is a multi-part process:
1) If you are updating the parent repository, make sure the update is fully functional. DO NOT send non-compiling code. - If you are updating to different repository (for example, a backup repository so that you can roll back to an earlier version of the code later), this does not apply.
2) Commit the changes. Inside the copied repository's folder, right-click and select "Hg Commit..."
Every commit requires a comment. This lets others viewing your update know why it was made. You will notice in the bottom-left part of the window where a list of files with check boxes to their left. The files listed are either completely new or have been changed. You can either click the checkbox at the top to select all of them, or select the files individually. All files checked will be submitted, with any changes, in the update. Finally, press commit to create the update.
-- If this is your first time creating an update on the computer you are working on, you will receive an error. On the message box, click the "close" button. In the Settings box that appears, put your first and last name in the "Username" field. Click "Apply", close the settings, and now you should be able to commit without error
3) The update you created is not automatically sent to the parent repository. That has to be done manually. Right-click the blank space inside your cloned repository and select "Hg Repository Explorer". Whenever you open the Repository Explorer, you should click on "Refresh". This will detect any updates created with commit. If you create an update while the Repository Explorer is open, you will also need to press "Refresh".
Before you can push your update, you must first pull new updates from the server. Make sure the parent repository is shown in the toolbar (see the image above for location of parent repository). Then, click "Synchronize" from the menu bar and select "Pull". Or, on the toolbar, press the button: 
If any new updates showed up, you may need to merge the changes before continuing (this will explained in the Merging section).
4) Finally, go to "Synchronize" and select "Push". Or, on the toolbar, press the button: 
. Assuming no errors, your update has been sent to the parent repository.
If another user has submitted an update to the parent repository, you can acquire that update using pull. Go to "Synchronize" and select "Pull". Once the update is shown in the Repository explorer, right-click the update and select "Update...", and press the update button to make the changes included in the updated to your child directory.
Merging
If you and another user are both applying updates to the parent repository, you will need to merge files.
In the most basic merge, a file incorporates changes from both users. This will be done when you receive an update from another user in the process of submitting your own update. Your update will show up in the Repository Explorer as its own branch. To merge the branch you created with the main one, right-click the newest update on the main branch (this should be the update that shows up at the top). Select "Merge with...". In the box that appears will be the "Merge Target" (what you are merging your update into), and the "Current Revision" (the update you created). There is also a check box. If you want to ignore the changes you made and just use the changes the from the other update, click that. Finally, press "Merge". If the merge was successful, press "Commit" to make the changes.
Note: If more than one person is working on the same file, it is important that you work on different sections of that file. Otherwise, you will encounter difficulty when merging,
