Add the distributed source control management tool mercurial.

1 files changed, 399 insertions, 0 deletions

diff --git a/mercurial.html.markdown b/mercurial.html.markdown
new file mode 100644
index 00000000..f7644f33
--- /dev/null
+++ b/mercurial.html.markdown
@@ -0,0 +1,399 @@
+---
+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/)
\ No newline at end of file