mirror of
https://github.com/adambard/learnxinyminutes-docs.git
synced 2024-12-23 09:41:36 +00:00
Add the distributed source control management tool mercurial.
This commit is contained in:
Will L Fife
parent
27fa7c50ce
commit
44c7eaad24
399
mercurial.html.markdown
Normal file
399
mercurial.html.markdown
Normal file
@ -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 permissions 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/)
|
||||
Loading…
Reference in New Issue
Block a user