DRBP Mercurial

Contents 1 Mercurial 1.1 Introduction 1.2 Main concepts in mercurial 1.3 Installing and configuring mercurial 1.4 A picture of mercurial environment 1.5 Repositories 1.6 Main mercurial commands for OB developers 1.6.1 hg clone 1.6.2 hg pull 1.6.3 hg update [hg up] 1.6.4 hg pull -u 1.6.5 hg commit [hg ci] 1.6.6 hg push 1.6.7 hg pull --rebase 1.6.8 hg st 1.6.9 hg diff 1.6.10 hg incoming [hg in] 1.6.11 hg outgoing [hg out] 1.6.12 hg strip 1.6.13 hg backout 1.6.14 hg revert 1.6.15 hg purge 1.6.16 hg transplant

Mercurial

Introduction

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:

• Installing Mercurial
• Configuring Mercurial

A picture of mercurial environment

Before check most useful commands of mercurial lets see this picture which will help us to understand them.

Repositories

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

hg clone

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

hg pull

This command will update your local repository, but it will not update the local files.

hg pull

hg update [hg up]

This command will update your local files based on the content of your local repository.

hg up

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

hg push

This command will move our commits from the local repository to the remote repository.

hg push 

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:

1. Extract our local changes and save them
2. hg pull -u is executed
3. Then our changes are commited again after the new ones

With this situation now we are ready to do hg push

hg st

This command will show us which files are different than the repository ones.

hg st 

•  ? -> (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

hg diff

This command will show us the changes that exist in our files comparing them against the local repository.

hg diff 

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 in

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 out

hg strip

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

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

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

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.

hg purge

other way do to the same is

hg st -u -n | xargs rm  (-u untracked files -n no tags)

hg transplant

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.