learnxinyminutes-docs/mercurial.html.markdown

---
category: tool
tool: hg
contributors:
	- ["Will L. Fife", "http://github.com/sarlalian"]
filename: LearnHG.txt
---

Mercurial is a free, distributed source control management tool. It offers you
the power to efficiently handle projects of any size while using an intuitive
interface. It is easy to use and hard to break, making it ideal for anyone
working with versioned files.

## Versioning Concepts

### What is version control?

Version control is a system that records changes to a file(s), over time.

### Centralized Versioning VS Distributed Versioning


* Centralized version control focuses on synchronizing, tracking, and backing 
up files.
* Distributed version control focuses on sharing changes. Every change has a 
unique id.
* Distributed systems have no defined structure. You could easily have a SVN 
style, centralized system, with mercurial.


### Why Use Mercurial

* Distributed Architecture
* Fast
* Platform Independent
* Extensible
* Easy to use
* Open Source


#### Distributed Architecture

Traditional version control systems such as Subversion are typical
client-server architectures with a central server to store the revisions of a
project. In contrast, Mercurial is truly distributed, giving each developer a
local copy of the entire development history. This way it works independent of
network access or a central server. Committing, branching and merging are fast
and cheap.


#### Fast

Mercurial's implementation and data structures are designed to be fast. You can
generate diffs between revisions, or jump back in time within seconds.
Therefore Mercurial is perfectly suitable for large projects such as OpenJDK
([hg](http://hg.openjdk.java.net/jdk7/jdk7)) or NetBeans
([hg](http://hg.netbeans.org/)).

#### Platform Independent

Mercurial was written with platform independence in mind. Therefore most of
Mercurial is written in Python, with a small part in portable C for performance
reasons. As a result, binary releases are available on all major platforms.


#### Extensible

The functionality of Mercurial can be increased with extensions, either by
activating the official ones which are shipped with Mercurial or downloading
some [from the wiki](https://www.mercurial-scm.org/wiki/UsingExtensions) or by
[writing your own](https://www.mercurial-scm.org/wiki/WritingExtensions).
Extensions are written in Python and can change the workings of the basic
commands, add new commands and access all the core functions of Mercurial.


#### Easy to Use

Mercurial sports a consistent command set in which most subversion users feel
right at home. Potentially dangerous actions are available via extensions you
need to enable, so the basic interface is easy to use, easy to learn and hard
to break. The [Quick Start](https://www.mercurial-scm.org/quickstart) should
get you going in a just few minutes.

#### Open Source

Mercurial is free software licensed under the terms of the [GNU General Public
License Version 2](http://www.gnu.org/licenses/gpl-2.0.txt) or any later
version.


## Terminology

| Term          | Definition                         |
| ------------- | ---------------------------------- |
| Repository    |  Collection of revisions           |
| hgrc          | A file which stores defaults for a repository. Global is ~/.hgrc and local is .hgrc inside the repository |
| revision      | Committed changeset, by REV number |
| changeset     | Set of work changes saved as diffs |
| diff          | Changes between files              |
| tag           | Name for a specific revision       |
| parent(s)     | Immediate ancestor(s) of revision or work |
| branch        | Child of a revision                |
| head          | A head is a changeset with no child changesets |
| merge         | The process of merging two HEADS   |
| tip           | Latest revision in any branch      |
| patch         | All diffs between two revisions    |
| bundle        | Patch with permis­sions and rename support  |


## Commands

### init

Create a new repository in the given directory, the settings and stored
information are in a directory named ".hg"

```bash
$ hg init
```

### help

Will give you access to a very detailed description of each command.

```bash 
# Quickly check what commands are available
$ hg help

# Get help on a specific command
# hg help <command>
$ hg help add
$ hg help commit
$ hg help init
```

### status

Show the differences between what is on disk and what is committed to the current
branch or tag.


```bash
# Will display the status of files
$ hg status

# Get help on the status subcommand
$ hg help status

```

### add

Will add the specified files to the repository on the next commit

```bash
# Add a file in the current directory
$ hg add filename.rb

# Add a file in a sub directory
$ hg add foo/bar/filename.rb

# Add files by pattern
$ hg add *.rb
```

### branch

Set or show the current branch name

*Branch names are permanent and global. Use 'hg bookmark' to create a
light-weight bookmark instead. See 'hg help glossary' for more information
about named branches and bookmarks.*

```bash
# With no argument it shows the current branch name
$ hg branch

# With a name argument it will change the current branch.
$ hg branch new_branch
marked working directory as branch new_branch
(branches are permanent and global, did you want a bookmark?)
```

### tag

Add one or more tags for the current or given revision

Tags are used to name particular revisions of the repository and are very
useful to compare different revisions, to go back to significant earlier
versions or to mark branch points as releases, etc. Changing an existing tag
is normally disallowed; use -f/--force to override.

```bash
# List tags
$ hg tags
tip                                2:efc8222cd1fb
v1.0                               0:37e9b57123b3

# Create a new tag on the current revision
$ hg tag v1.1

# Create a tag on a specific revision
$ hg tag -r efc8222cd1fb v1.1.1
```

### clone

Create a copy of an existing repository in a new directory.

If no destination directory name is specified, it defaults to the basename of
the source.

```bash
# Clone a remote repo to a local directory
$ hg clone https://some-mercurial-server.example.com/reponame

# Clone a local repo to a remote server
$ hg clone . ssh://username@some-mercurial-server.example.com/newrepo

# Clone a local repo to a local repo
$ hg clone . /tmp/some_backup_dir
```

### commit / ci

Commit changes to the given files into the repository. 

```bash
# Commit with a message
$ hg commit -m 'This is a commit message'

# Commit all added / removed files in the currrent tree
$ hg commit -A 'Adding and removing all existing files in the tree'

# amend the parent of the working directory with a new commit that contains the
# changes in the parent in addition to those currently reported by 'hg status',
$ hg commit --amend -m "Correct message"
```

### diff

Show differences between revisions for the specified files using the unified diff format.

```bash
# Show the diff between the current directory and a previous revision
$ hg diff -r 10

# Show the diff between two previous revisions
$ hg diff -r 30 -r 20
```

### grep

Search revision history for a pattern in specified files

```bash
# Search files for a specific phrase
$ hg grep "TODO:"
```

### log / history

Show revision history of entire repository or files. If no revision range is
specified, the default is "tip:0" unless --follow is set, in which case the
working directory parent is used as the starting revision.

```bash
# Show the history of the entire repository
$ hg log

# Show the history of a single file
$ hg log myfile.rb

# Show the revision changes as an ASCII art DAG with the most recent changeset
# at the top.
$ hg log -G
```

### merge

Merge another revision into working directory

```bash
# Merge changesets to local repository
$ hg merge

# Merge from a named branch or revision into the current local branch
$ hg merge branchname_or_revision

# After successful merge, commit the changes
hg commit
```

### move / mv / rename

Rename files; equivalent of copy + remove. Mark dest as copies of sources;
mark sources for deletion. If dest is a directory, copies are put in that
directory. If dest is a file, there can only be one source.

```bash
# Rename a single file
$ hg mv foo.txt bar.txt

# Rename a directory
$ hg mv some_directory new_directory
```

### pull

Pull changes from a remote repository to a local one.

```bash
# List remote paths
$ hg paths
remote1 = http://path/to/remote1
remote2 = http://path/to/remote2

# Pull from remote 1
$ hg pull remote1

# Pull from remote 2
$ hg pull remote2
```

### push

Push changesets from the local repository to the specified destination.

```bash
# List remote paths
$ hg paths
remote1 = http://path/to/remote1
remote2 = http://path/to/remote2

# Pull from remote 1
$ hg push remote1

# Pull from remote 2
$ hg push remote2
```

### rebase

Move changeset (and descendants) to a different branch

Rebase uses repeated merging to graft changesets from one part of history
(the source) onto another (the destination). This can be useful for
linearizing *local* changes relative to a master development tree.

* Draft the commits back to the source revision.
* -s is the source, ie. what you are rebasing.
* -d is the destination, which is where you are sending it.

```bash
# Put the commits into draft status
# This will draft all subsequent commits on the relevant branch
$ hg phase --draft --force -r 1206

# Rebase from from revision 102 over revision 208
$ hg rebase -s 102 -d 208
```

### revert

Restore files to their checkout state. With no revision specified, revert the
specified files or directories to the contents they had in the parent of the
working directory. This restores the contents of files to an unmodified state
and unschedules adds, removes, copies, and renames. If the working directory
has two parents, you must explicitly specify a revision.

```bash
# Reset a specific file to its checked out state
$ hg revert oops_i_did_it_again.txt

# Revert a specific file to its checked out state without leaving a .orig file
# around
$ hg revert -C oops_i_did_it_again.txt

# Revert all changes
$ hg revert -a
```

### rm / remove

Remove the specified files on the next commit.

```bash
# Remove a spcific file
$ hg remove go_away.txt

# Remove a group of files by pattern
$ hg remove *.txt
```

## Further Information

* [Learning Mercurial in Workflows](https://www.mercurial-scm.org/guid)
* [Mercurial Quick Start](https://www.mercurial-scm.org/wiki/QuickStart)
* [Mercurial: The Definitive Guide by Bryan O'Sullivan](http://hgbook.red-bean.com/)