Mercurial - Part 1

These notes describe things about Mercurial. There are two parts. The first part puts forth
1) How to setup Mercurial on a Linux machine
2) How to use it the very first time after setup is complete
3) How to push your data to the central repository

Purpose - Setup and use Mercurial

Settingup Mercurial

Install and configure

Mercurial has dependencies
secure shell (ssh) is the first dependency as the fabacademy server expects a secure access. If ssh is not already installed then

sudo apt-get install ssh

This is a good tutorial that I followed initially and then could do the same on another machine, on my own.

Install Mercurial
sudo apt-get install mercurial

Configure Mercurial to be used in synch with Fabacademy

---yet to add---

Clone

Assuming the setup and configuration is working correct, cloning the central repository is next step. For that let us go to the appropriate directory depth. In my case it is:

(user):~/Documents/personal/Fablab/academy/2014/academy.2014.

On terminal, CDing to this location and then executing following command starts making an exact copy (clone) of the central repository.

sudo hg clone -e "ssh -p 846 -i ~/.ssh/keys/academy" ssh://hg@fabacademy.org/academy.2014 academy.2014

Cloning takes some time. It might do this for hours, depending upon bandwidth and the size of the repository. One has to wait!!

Caution: I experienced, if Cloning is interrupted everything that was cloned is lost! I have done this many a times in 2011 and 2 times this year.

/tmp$ sudo hg clone -e "ssh -p 846 -i ~/.ssh/keys/academy" ssh://hg@fabacademy.org/academy.2014 academy.2014
requesting all changes
adding changesets
^Ctransaction abort!
rollback completed
interrupted

Use for first time

Assumptions:

1) The repository at fabacademy.2014 has already been cloned. "hg clone" is not covered in this write-up. We will make a separate note of this. That means this write-up applies only if, the target machine already has "cloned" the Repository from Fabacademy server.

2) The path to "cloned" repository (as an example, addressed as repo_path):

repo_path = home/(user)/Documents/Fablab/Academy/2014/academy.2014

Steps to create one's own folder in the rpository:

1) following is to be done through Terminal. This has been tested on Ubuntu only.
2) Go to the entry point of cloned repository (here inside the folder - fabacademy.2014)

cd (repo_path)/academy.2014

Now prompt should look like this (pc-name):(repo-path). Please note that academy.2014 was created while cloning, by the user. hgi Execute the following command

ls -l -a

Output should contain following list, along with other details (permissions, date etc.)
.
..
.DS_Store
.hg
.hgignore
Web

If the output does not include this list (specifically .DS_store, .hg and .hgignore), then there is some issue with the "hg clone" command, that you had used.

3) Now, that cloning is over, next step is to pull from the central repository. While, cloning was happening, someone might have made chages and uploaded to the central repository. This keeps happening dynamically. Hence pulling the latest changes now and then, makes sense.

sudo hg pull

This will pull the latest additions from server repository (also called as "main repo" in this writeup). 4) while "hg pull" is helpful in getting all the latest changes made by others to different folder, it does not pull the data from "Wrking Directory". To get the latest data from Working Directory

sudo hg update

This should not impact us at this moment, as there is nothing to be updated for us. Because at this moment we have not added any directory from our side (also called as "Working Directory").

5) This is time, a Working Directory needs to be created, moving towards creating a prsence on fabacademy server! if Output in Step 2 was as expected then Web/students should be present.

cd Web/students
sudo mkdir (student's name) (e.g. sudo mkdir firstName.secondName)

Caution: Please note not to create the directory anywhere else in the repository. This less technical and more an orgnisational and social need.

6) Go into the Working Directory, and create the index.html page. It seems the web-server handling the fabacademy-2o14 looks for index.html in each directory inside the repository. If index.html exists then that becomes the entry point.

. as expected then Web/students should be present.

cd (student folder)
sudo touch index.html

This will create a file called "index.html". index.html is must because that is how the Server will expect the entry point to the website.

7) index.html can now be populated with a sample text.

sudo gedit index.html

This will open the index.html file in edit mode. A few sample lines are pasted below. If knowing HTML is a problem for now, we can use the following, just to move ahead for now -

Who@fabacademy 2014

Hello. This is the first ever page. Uploading many, very soon

save and close. This will take the control back to Prompt.

Now, henceforth, opening and editing this index.html would eventually become frequent!

8) At this stage, in the Working Directory, a folder (correspomnding to a specific student) containing index.html is ready. However, this is on local repository, nit yet on the central repository.

cd (repo-path)
sudo hg status

one should now see a message, similar to

? firstName.secondName

At this point we have confirmed that the changes we did in the folder have been noticed by mercurial.

9) Now, before uploading the changes to the central repository, it makes sense to do a pull

hg pull

to get the newly added files from server, if any.

Doing a "hg update" now, will delete the changes we just made. So this is not appropriate time to do an update of Working Directory. 10) again to check what changes we have made to the local repository:

hg status

If anything in addition to ? firstName.secondName is seen, there is some issue.

Note* My limited experience does not answer this situation! I would suggest to resolve this collectively by consulting with the academymates.

11) At this point in time the Working Directory is ready and we can push it to the central repository. To do so, prompt should remain at (repo-path) :

hg add

See if a message similar to adding firstName.secondName is shown.

12) Previously (at step 10) mercurial had noticed the changed but did not know what to do with (hence ? mark). Now, at this stage, we have explicitely told mercurial to consider this change as a valid one. Hence, status should be different now.

hg status

The output in this case will be similar to:

A firstName.secondName

13) There is another check - This is another check to see what is new in the Working Directory that should be outgoing to the central repository.

hg outgoing

Note* Here too, one should see only the files/folders that were just created and modified. If anything in addition to that then there is some issue.

14) At this moment, because some time has passed pulling again from the central repository might (afterall how many times one would pull such as dynamic repository in a short sapn of time!!) be a good idea - Very Relative...

hg pull

15) At this stage it is time to let mercurial know that the contents are definitely to be pushed ... but just letting it know and not asking to do it yet!!

hg commit -m "some relevant message for future reference"

16) (... THE last step ...)

hg push

if a success message takes place, things is over.

If any other message is seen, for example about "creating heads"

abort: push creates new remote head 7a0b487d19af!

(you should pull and merge or use push -f to force)

STOP. In case of issues while doing "hg push", the output message might show a FORCE option. Let us NOT Force. Forcing will impact the whole community.