mirror of
https://github.com/adambard/learnxinyminutes-docs.git
synced 2024-11-27 04:44:08 +03: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