Mercurial tutorial
From TremFusion
Contents |
First use
Setting a username
First, you have to give a name to mercurial to identify yourself. Your username will be reported on commits you make. Edit or create your mercurial configuration file ($HOME/.hgrc) and add following:
[ui] username = Ano Nyme <ano.nyme@nowhere.here>
Get a project
To begin to work on a project, you need to retreive it on your local desktop. So, you have to clone a repository.
$ hg clone http://www.tremfusion.net/hg/tremfusion tremfusion
Wait. You have now all depository, with all revisions since project startup.
Create a project
You probably don't need to create a project, but if you do, the command is
$ hg init directory_source
hg init will convert unrevisioned directory to a mercurial depository.
Changeset, Parents
Basicly, A changeset is a step made for the project developpement. So, a changeset contain:
- An identifier. An identifier has two parts: a short and local identifier (it's 0 for first changeset and increment for each changset), and a common changeset, what is an hexadecimal key. When you use mercurial on your local desktop, you can use local changeset identifier. But changeset identifier is sometime different on other developper's depository. So, when you need to identify a changeset between two depository, use global changeset identifier.
- A patch with all modifications done
- A list of parents
- A changset summary (a comment to annotate what is new with this changeset)
See changeset logs
To see all changeset made from the project beginning
hg log
You probably have to pipe command with a ``less on projects with many changsets.
You can also use ``-l n option to see only `n' last changesets.
hg log display only first summary line. To display all summary, use mercurial verbose mode:
hg -v log
Get project sources state from a changeset
You will probably use the last changeset most part of the time (the newest version of sources). But sometime, you will probably had to use older project sources. You can get sources at changeset you hope with command:
hg update changeset_identifier
Changeset identifier can be a local identifier, a global identifier (hexadecimal string), a branch name or a tag (see bottom)
See diff file between two changeset
To see exactly what's new with a changeset, you need to have diff files of a changeset:
hg diff -r older_changeset:newest_changeset
Don't forget to filter result with a less-like command :)
Get a global view of a mercurial depository
With command:
hg tree
you can get a graphical view of depository and see all modifications made on each changeset. This command give nothing else more than ``log and ``diff commands, but is easiest to use with mouse. Use this command when you need to make a long visualisation work with depository.
Modify sources
See files state
To see files state (new files, modified files, ...) use:
hg status
hg status print all files with status different with last changeset status. Files have an annotation at left of their names to give informations about their status:
- ?: mercurial don't know this file. Maybe it is a useless file for mercurial (a binary, an object file, etc...), or maybe it is a new file you forget to add. You can make filters in ? files to don't display some files in a .hgignore file (see later)
- M: modified file. File exist in last changeset, but there is differences between changeset version and current file.
- A: added file. File is added with a hg add command and must be commited to appair on next changeset
- !: mercurial know this file, but it can't find this file in current source tree. It is an error (maybe you forgot to remove this file with hg remove command ?)
- R: removed file. File existed in last changeset, but it is will be deleted on next commit.
- there is some other uncommon file status... Make hg help status for more details.
See diff files between current sources and last changeset
To see diff you made from last changeset, make a simple:
hg diff
without any argument.
Add/Remove files from repository
If you add a new file in repository, or if you want to remove a file from repository, you have to use commands:
hg add file_list hg remove file_list
if a file is a directory, file will be added/remove recursively
Commit a changeset
When you made all modifications you need, you can make a commit:
hg commit
mercurial will open your favorite editor (defined with EDITOR environement variable), then write a summary. Summary have to be short, but have to be a good explenation of changeset you made. Summary will be the way to identify your changeset in hg log.
Use tags and branches
- TODO*
Retreive/Distribute changeset from another depository
Retreive new changesets
To retreive new changeset from depository where you initialized your depository with hg clone command, make command:
hg pull
if you add an address in argument of pull' command, you can retreive changeset from another depository.
Distribute new changesets
To distribute new changeset to depository where you initialized your depository with hg clone command, use:
hg push
if you add an address in argument of push' command, you can distribute changeset to another depository.
Concurrent developpement
- TODO*
