Mercurial intro

What will we talk about?
● The .hgrc
● A Stack of Patches
● Basic Commands
● Branching, pushing, pulling
● Howtos

Assumptions
● You have some programming knowledge
● You know the basics of some version control
system
○ git
○ svn
○ cvs
○ mercurial
○ ...

.hgrc!

Who has no
.hgrc?

Why .hgrc?
● Username
● Extensions
● Aliases
● Other settings
● Example:
○ http://confluence.incubaid.
com/display/ENG/Incubaid+Starter+Kit

What is .hgrc
● Configuration for your Mercurial
● INI file format
○ # Comments
○ [sections]
○ key = value

Minimal .hgrc: Username
[ui]
username = John Doe <john.doe@example.com>

.hgrc: Extensions
● Mercurial without extensions is barely
useable
● Small core, but easy to extend
● Extensions add some sugar
● Python scripts
○ Write your own!

.hgrc: Extensions
[extensions]
pager = # pipe through less automatically
color = # Color output
graphlog = # ASCII art graphical logs
fetch = # Pull-and-merge, use with care
mq = # Strip, flexible commit queues
highlight = # syntax highlighting in hgweb

.hgrc: aliases
[alias]
blame = annotate -u
out-diff = out -pvM
in-diff = in -pvM
# Show the diff of a given changeset ID
show = log -p -v -r

How to think about Mercurial

It's a stack of patches
with downward links between them

A Stack of Patches
Working directory
commit
@ 4:ch4ch4: Change number 3
Parent: ch3ch3
tag: tip
Top of the
stack

Patch Save Time
3:ch3ch3: Merge in Alice's work
Stack index Parent: ch2ch2
Clone- Parent: al1al1
dependent!

Node ID 2:ch2ch2: Change number 2
Unique! Parent: ch1ch1

1:al1al1: Alice's changes
parent: ch1ch1 is-child-of

0:ch1ch1: Change number 1
Root commit Parent: ch0ch0
Identifies a repository

What is a commit?
● Diff
● Metadata
○ timestamp
○ user SHA1 Unique Commit
○ branch? ID
○ parent(s): 1 or 2
○ ...
● If you change any of these fields:
○ commit ID will change
○ you create a different commit!

Cause of all those merges

Local repository status:

Parent: ch1ch1



Pull from Alice's repository:

parent: ch1ch1

No re-ordering can 1:ch2ch2: Change number 2
Parent: ch1ch1
happen without altering
the tags and therefore the
unique hashes of the
commits!

2 'heads'!

parent: ch1ch1

Parent: ch1ch1


We want one 'head'!

3:ch3ch3: Merge in Alice's work
Parent: ch2ch2
Parent: al1al1

parent: ch1ch1

Parent: ch1ch1


-> We need to merge. :-(

Quiz 1
● What is .hgrc good for?

Quiz 1
○ Username
○ Extensions
○ Aliases
○ Much, much more

Quiz 1
○ Username
○ Extensions
○ Aliases
○ Much, much more
● How should you imagine a Mercurial
repository?

Quiz 1
○ Username
○ Extensions
○ Aliases
○ Much, much more
● How should you imagine a Mercurial
repository?
○ As a stack of patches.

Basic Commands
● help
● clone
● init
● add/remove/addremove
● cp/rename/mv
● status
● diff
● commit

Help!
● hg help: General help
○ List of commands
○ List of extensions
○ Additional help topics (advanced stuff)
● hg help <command>
○ hg <command> --help

Cloning a repository
● hg clone <remote> <foldername>
● Creates a .hg folder in <foldername>
● Downloads all the patches/commits from
<remote>
● Checks out the files of the last commit on the
default branch on your disk, in <foldername>

Init: Creating a new repository
● hg init <foldername>
● Creates a .hg folder in <foldername>
○ No commits yet
○ No changes yet

Add/Remove/Addremove
● hg add <path>
○ 'enables' <path> for committing
● hg rm <path>
○ 'disables' <path> for committing
● hg addremove <path>
○ "Add all new files and remove all missing files from
the repository."
○ Use with care (.hgignore!)
● Paths either absolute or relative to $PWD!
○ <> 'hg status' output

cp/rename/mv/move
● Avoid having to add/rm
● hg cp
● hg rename
○ Aliases: mv, move

Status
● Show which files are:
○ Added (A)
○ Removed (R)
○ Modified (M)
○ Missing (!) - use hg rm
○ Not tracked (?) - use hg add
● Paths relative to repository root (annoying)
○ Try hg status .
○ Mercurial 1.7 or higher:
■ Alias: stat = !hg status $($HG root) $HG_ARGS

.hgignore
● Tell Mercurial to ignore files in your
repository
○ mycode.pyc
○ README.txt~
○ mycode.py.orig
○ mycode.py.rej
○ ...
● 2 ways of matching
○ Regex (default)
■ .pyc$ or re:.pyc$
○ glob (~bash)
■ glob:**.pyc
● Located in `hg root`

.hgignore: Example
syntax: glob
doc/*.aux
doc/_build/html
dist/*
arakoon.native
**.pyc
syntax:regexp
^_build
~$

locate: test a pattern
● "locate files matching specific patterns"
● hg locate "glob:**.py"
○ The quotes are needed to avoid your shell
expanding the '*'
● Only prints files under Mercurial control
○ Like find, but limited to 'tracked' files.

Diff: what did I change?
● hg diff
● Changed files:
○ Show diff with previously committed version
● Added files:
○ Show content
● Removed files:
○ Show content
● Specify <path>
○ Diff only that file/those files
○ Can use re: and glob:
● USE COLOR !!!

Color extension
● .hgrc
● [extensions]
color =
● Colors can be customized
● Adds color to almost all commands that have output
○ status
○ diff
○ log
○ ...

Commit: Create a new commit
● hg commit
○ Username
■ from .hgrc (preferably!)
■ -u "Joske Vermeulen <joske@incubaid.com>"
○ Commit message
■ in editor (default)
■ -m "My commit"
○ Files
■ Default: everything shown as A/R/M in status
■ Use -I and -X for more control (re, glob)
● Creates a new commit
● Use nice commit messages

Log: check the history
● hg log
● Order: stack of patches!
● Spammy? There's an extension for that!

[extensions]
pager =

[pager]
pager = less -R
attend = annotate, cat, df, diff,
>>glog, help, in-diff, incoming,
>>log, out-diff, outgoing, qdiff,
>>show, tip, grep

Graph log
● Useful when branching, merging, ...
● ASCII art graphs!
● Need to enable the extension
○ [extensions]
graphlog =
● hg glog
● @ marks the working directory commit

Quiz 2: basic hg commands
● Start tracking an untracked file?

○ hg add <path>

○ hg add <path>
● Print the root of the repository you're in?

○ hg add <path>
○ hg root

○ hg add <path>
○ hg root
● Commit only one file when multiple are
changed?

○ hg add <path>
○ hg root
changed?
○ hg commit -I <path>

○ hg add <path>
○ hg root
changed?
● Command to show an ASCII art log graph?

○ hg add <path>
○ hg root
changed?
○ hg glog

○ hg add <path>
○ hg root
changed?
○ hg glog
● Mark for the working directory commit?

○ hg add <path>
○ hg root
changed?
○ hg glog
● Mark for the working directory commit?
○ @

Branching, pushing, pulling
● branch
● update
● identify
● push
● pull
● incoming, outgoing

Branching...
● Not very flexible in Mercurial
○ Unique branch names
○ No branch renames
○ Branch name must be chosen before first commit on
that branch
○ ...
● Just adds a "branch=name" to the metadata
of a commit.
● Default branch has no "branch=default"
● Interesting comparison: http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/

Back to the stack of patches...
8:cb2cb2: Also on the branch
Parent: cb1cb1
branch: mybranch
tag: tip

hg update mybranch

Patch Save Time
Parent: ch4ch4

hg update default
6:cb1cb1: Branching!
Parent: ch3ch3
branch: mybranch

hg update 4 && hg branch mybranch
Parent: ch3ch3

Parent: ch2ch2

Branch-related commands
● hg branch
○ What branch am I on?
● hg branches
○ What branches are there?
● hg branch <name>
○ Create a branch with <name>

Update
● Changes the working directory commit (@)
○ hg update <branchname>
■ Go to the last commit on branch <branchname>
○ hg update <rev>
■ Go to revision <rev>
● Discard local changes (danger, no backup!)
○ hg update --clean ...
○ Forces the update

Identify
● Prints the working directory commit (@)
● hg identify
c640c961a243 tip

Push
● Send changesets not yet at <remote> to
<remote>
● hg push
○ Push to 'default'
● hg push ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1
○ Explicit target
● hg push default
○ Push to 'default' path explicitly.
○ Define 'default' (and others) in .hg/hgrc
● Protocol: SSH or HTTP (or local)

Push: 'shortcuts'
.hg/hgrc:
[paths]
default = ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1
private = ssh://hg@bitbucket.org/geiregaj/pylabs-core-5.1-jens

hg paths
● Prints the named paths for the repository:
○ $ hg paths
default = ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1
private = ssh://hg@bitbucket.org/geiregaj/pylabs-core-5.1-jens

Push -b
● hg push -b default ssh://...
● Push one branch
○ Keeps the <remote> clean
○ Push your branch to a private repository, after merge
push to the common repository

hg duw
● [alias]
duw = push -r .
● Pushes your working directory commit (@)

Pull
● hg pull
● hg pull default
● hg pull ssh://hg@bitbucket.org/incubaid/pylabs-core-5.1
● Downloads the changesets that are on
<remote> but not on <local>
● Shortcut: hg pull -u
○ == hg pull && hg update
● Tip will be the newest of the pulled commits

Incoming, outgoing
● Show commits that would be pulled or
pushed
● Useful as a quick check without the danger
of pulling things you don't want yet.

Quiz 3
● Why do you need to commit to create a
branch?

Quiz 3
branch?
○ Because branches only really exist in the commits,
as a tag. No commit means no tag. No tag means no
branch.

Quiz 3
branch?
as metadata. No commit means no metadata. No
metadata means no branch.
● How to print all branch names?

Quiz 3
branch?
○ hg branches

Quiz 3
branch?
○ hg branches
● How to find out what your working directory
commit is?

Quiz 3
branch?
○ hg branches
● How to find out what your working directory
commit is?
○ hg identify
○ hg glog and search for the '@'

Howto's
● Merge
● Discard changes
● Collaborate
● Feature branches
● Commit message template
● (Bitbucket) SSH keys
● Remove a commit
● Undo a commit

How to Merge
● This is where things typically go wrong.
○ Merge direction...
○ > 2 heads
○ Conflicts (oh noes!)

Merge Direction: Goal
● A small diff!
○ Keeps your tools from choking on HUGE diffs
● From hg merge --help
○ The current working directory is updated with all
changes made in the requested revision since the
last common predecessor revision.

Merge Direction
1. Create your local commit
2. Pull in the latest changes from <remote>
3. Check the situation with
a. hg glog
b. hg heads
4. Decide on the merge direction
5. hg update <base> (if needed)
6. hg merge
7. Check the merge (tests?)
8. Commit

Merge Direction
Parent: ch6ch6

Parent: ch5ch5

Pulled
Parent: ch4ch4
@ 6:abcabc: My change
Parent: ch2ch2
Parent: ch3ch3

Parent: ch2ch2

Merge Direction
hg update ch7ch7
@ 9:ch7ch7: Change number 7
Parent: ch6ch6

Parent: ch5ch5

Pulled 10 changes
Parent: ch4ch4
@ 6:abcabc: My change
Parent: ch2ch2
Parent: ch3ch3

1000 changes 4:ch3ch3: Change number 3
Parent: ch2ch2

@ 9:ch8ch8c: Merge
Parent: ch7ch7
Merge Direction Parent: abcabc

Parent: ch6ch6 hg merge
hg commit
Parent: ch5ch5
-m "Merge"
Pulled
Parent: ch4ch4
6:abcabc: My change
Parent: ch2ch2

Parent: ch3ch3

Parent: ch2ch2

Merge: > 2 heads
● Mercurial can only merge 2 heads / commit
● To merge > 2 heads, merge multiple times
○ Choose head with most changes (biggest diff)
○ hg update <bighead>
○ hg merge <smallerhead>
○ hg commit
○ -> repeat

Merge: conflicts
● kdiff3
○ 3-way merge tool
○ Powerful
○ Simple to use
○ Install it and configure it in your .hgrc
■ or use my example config...

Merge: conflicts Next unmerged conflict
Choose
● Kdiff3! line
Common ancestor Local
Remote

Result: Edit by clicking A/B/C or by manually editing the text

Merge: conflicts
● Kdiff3 workflow:
○ Fix all unmerged conflicts
■ use triple arrows to find them
■ A/B/C or manual edit
○ When all unmerged conflicts are resolved
■ Click 'save'
■ Exit kdiff3

Howto: discard changes
● You changed or removed a file
● But want to restore it to how it looked in the
last commit
○ hg revert <path>
● Shortcut: revert everything:
○ hg revert --all
● The content before the revert is saved with
suffix .orig
● Revert to a specific revision
○ hg revert -r abcabc <path>

Howto: Collaborate
● Avoid working on the same files at the same
time
○ Same for moving files that other people are working
on
● Push your code often
○ What if you lose your laptop?
○ If you don't want to push to the main repository,
create a private clone on Bitbucket
● Merge with care
● But...
○ what if Bitbucket goes down?!

Howto: Collaborate
● hg serve to the rescue!
● Runs an HTTP server
○ Browse your repository
■ Useful for quick reviews!
○ Pull code from it
■ hg pull http://my.ip.com:8000/
● hg serve is built-in

Howto: Collaborate
● Default push/pull 'protocol': SSH
● Allows pushing (hg serve does not, by
default)
● hg push ssh://user@host/home/user/repo/path/
○ Use SSH keys

Howto: Feature Branches
● Upside:
○ Develop your feature without messing up the
'default' branch of the repository
● Downside
○ amount of branches might become very large...
■ Close your feature branches
■ Use clones, bookmarks, ...

Howto: Feature Branches
Feature merged into
default D6
No choice about merge direction
here. D5 B5 Use --close-branch
D4 B4 Merge latest
default
D3 B3 hg merge default

B2

D2 B1 Feature branch
D1

Default D0

Howto: commit message template
● .hgrc:
○ [ui]
username = Jens Geiregat <...>
editor = /usr/bin/vim -c "r ~/.hgtemplate"
○ vim 'command' r[ead] <path>
● .hgtemplate:
○ """

Reference:

Signed-off-by:
"""

Howto: (Bitbucket) SSH keys
● Easier pushing and pulling from Bitbucket
● Easy to set up
○ http://bit.ly/S4l1ly
● Invest 2 minutes, gain years of easier
Bitbucket interaction.
● Also useful for non-Bitbucket servers
○ Use ssh-copy-id to publish your public key to a
remote machine

Howto: Remove a commit
● Removes a commit and every commit
depending on it
○ DANGER!
○ Creates a backup in .hg/strip-backup as a bundle
○ Can only be used when the strip happens on ALL
clones that contain the stripped commit(s).
● Part of the mq extension:
○ [extensions]
mq =
● Bitbucket can strip too
○ Part of the admin interface

Howto: undo a commit
● Commit the inverted patch of a previous
commit
● hg backout <rev>

Quiz 4
● What is the command to discard changes?

Quiz 4
○ hg revert

Quiz 4
○ hg revert
● What 'protocols' can be used for push/pull?

Quiz 4
○ hg revert
○ SSH and HTTP

Quiz 4
○ hg revert
○ SSH and HTTP
● Which head should you merge to?

Quiz 4
○ hg revert
○ SSH and HTTP
● Which head should you merge to?
○ The one with the most changes

End of the basics.
● But there's much, much more.
○ 'Advanced' commands (cat, archive, locate, grep)
○ revsets
○ mq
○ (let me know what you would like to know)
○ Anyone interested?
● Links:
com/display/ENG/Incubaid+Starter+Kit
com/display/ENG/Mercurial+Cheat+Sheet+-
+Hg+Cheat+Sheet
○ http://hginit.com/
○ http://hgbook.red-bean.com/

Advanced
● hg cat ● hg recover
● hg archive ● hg resolve ?
● hg bisect ● hg revert
● hg copy ? ● hg rollback
● hg grep ● ext: record
● hg locate

Mercurial intro

More Related Content

Viewers also liked (14)

Similar to Mercurial intro (20)

Recently uploaded (20)

Mercurial intro