Mercurial is a cross-platform, distributed revision control tool for software developers. It provides to developers the following advantages.
- It will track the history and evolution of your project, so you don't have to. For every change, you'll have a log of who made it; why they made it; when they made it; and what the change was.
- When you're working with other people, revision control software makes it easier for you to collaborate. For example, when people more or less simultaneously make potentially incompatible changes, the software will help you to identify and resolve those conflicts.
- It can help you to recover from mistakes. If you make a change that later turns out to be in error, you can revert to an earlier version of one or more files. In fact, a really good revision control tool will even help you to efficiently figure out exactly when a problem was introduced (see the section called “Finding the source of a bug” for details).
- It will help you to work simultaneously on, and manage the drift between, multiple versions of your project.
Main concepts in mercurial
- Repository: A remote copy of a source tree with revision history. More
- Working Copy: Also known as working directory. It's the top-level directory in a repository, in which the plain versions of files are available to read, edit and build. More
- Changeset: It's a collection of all the changes that lead to a new revision of the repository. More
- clone: a complete copy of a repository. More
- pull: a pull propagates changesets from a "remote" repository (the source) into a local repository (the destination). More
- update: it updates the working directory from the repository. More
- commit: commit changes to the given files into the repository. More
- push: to send all differing revisions to another repository. More
- tag: to name a particular revision. More
- branch: a diverging point in time in the revision history. More
- head: repository heads are changesets that don't have child changesets. They are where development generally takes place and are the usual targets for update and merge operations.
- tip: The tip revision (usually just called the tip) is the most recently added changeset in the repository, the most recently changed head.
Installing and configuring mercurial
Check these articles:
A picture of mercurial environment
Before check most useful commands of mercurial lets see this picture which will help us to understand them.
Each developer should work against his local repository and just when the development/fix is completed and tested locally it will be sent to the "main" repository.
Main mercurial commands for OB developers
This command should be used just to create new local repository based on mercurial repositories which already exists.
hg clone https://code.openbravo.com/erp/devel/pi
It will create by default a new folder called "pi" in the folder where the clone command was executed. If we want to download the contents into a different folder a new argument can be passed to this command indicating the destination.
hg clone https://code.openbravo.com/erp/devel/pi myDestinationFolder
It's recommended to have and maintain updated a copy of the repositories which can be used to be cloned when needed, without depend on internet and helping us to be faster in the process to create working copies. To do it just make a clone of your repository.
hg clone mylocalrepository mynewlocalrepository
This command will update your local repository, but it will not update the local files.
hg update [hg up]
This command will update your local files based on the content of your local repository.
hg pull -u
This is one of the most common commands used on mercurial because it is used to do a complete update (repository + files) of our working copy. This command will perform hg pull and then hg up.
hg pull -u
hg commit [hg ci]
This command allow us to commit locally a certain change. That change should provide a correct message which will indicate what this change do. Remember that A local commit is just a change in your local repository. It will not be part f the main repository until hg push is done.
hg ci -m "Commit explanation"
In order to ensure which files are you going to include in a commit the following commands are very useful:
hg st hg diff hg log
This command will move our commits from the local repository to the remote repository.
If you are pushing data to main repository (test), you should ensure that this changes are completed and working fine. Never push unstable changes
hg pull --rebase
This command is very useful when new changes has been added to the repository while you have been developing in your local repository. In this situation, we are not allowed to create new heads so hg push will not work.
This command execute the following steps:
- Extract our local changes and save them
- hg pull -u is executed
- Then our changes are commited again after the new ones
With this situation now we are ready to do hg push
This command will show us which files are different than the repository ones.
- ? -> (unknown files) files found in your working copy but not part of the repository.
hg st -u
- M -> (modified files) Files which are part of the repository but are different in your working copy.
hg st -m
- ! -> (removed files) Files which are part of the repository but doesn't exists in your working copy.
hg st -r
- A -> (Added files) New files of your working copy which have been added to he local repository through hgg add
hg st -a
This command will show us the changes that exist in our files comparing them against the local repository.
Also is possible to see which have changed between fifferent revisions of our code
hg diff -c changeset
We can save the differences into a file using the following command
hg diff > mydifferences.diff
File generated in the previous step can be used as a patch
patch -p1 < mydifferences.diff
hg incoming [hg in]
This command shows us the commits which are pending to be included into our local repository. It means, it shows the commits which will be imported when hg pull is performed
hg outgoing [hg out]
This command shows us the commits which are pending to be pushed to the remote repository. It means, it shows the commits which will be pushed when hg push is performed
hg strip removes the changeset and all its descendants from the repository. It will be as if the changes never existed.
This command just can be used to revert things when they are not pushed to the repository.
hg strip rev
hg backout creates a new changeset to reverse the effect of an earlier changeset. The old changeset will still remain in the repository but so will a new changeset to remove the changes. It can be used to revert things when they are not pushed to the repository.
hg backout -r rev
hg revert updates the working copy to the specified revision. Normally to the current revision. This command will modify the specified files to match with the repository information.
hg revert file (revert changes on specified file) hg revert file --no-backup (revert changes on specified file without backup) hg revert -a (revert all the files) hg revert -a --no-backup (revert all the files whithout create a backup)
hg purge removes every untracked files. Caution! if you have created a new fle which is not added to the repo this command will remove it.
other way do to the same is
hg st -u -n | xargs rm (-u untracked files -n no tags)
This command is usefull to move one commit from one repo to other repository.
hg transplant -s sourcerepo rev
If you have problems during the transplant and you need to do any merge, you should use
hg transplant --continue
when the merge is done.