Mercurial: the definitive guide#
This is a work in progress to get a new (third) edition of the Mercurial book using a modern build system based on Jupyter Book, with notebooks written as MyST markdown files using the Bash kernel.
The first edition of the book was authored by Bryan O’Sullivan and published by O’Reilly in 2009. Work on the second edition of the book was started in 2015 by Mathias De Maré. However, since 2015 (7 years ago!), Mercurial improved quite a lot! This new edition should present Mercurial as it is in 2023.
Warning
The content of the book has not yet been updated and therefore does not yet reflect modern Mercurial usage!
This project is now hosted on foss.heptapod.net. The recommended way to contribute is to create a Topic based Merge Request on https://foss.heptapod.net/mercurial/mercurial-jupyterbook.
Target TOC for the new edition (to be discussed)#
Getting started#
Install Mercurial and extensions + configuration
A tour of Mercurial: the basics
Built-in help
Create a repository (init or web + clone)
Notion of working directory
Tracked files (example with simple Python code,
status
,add
, .hgignore)Shorter names for commands (
st
)Commit as a snapshot of the tracked files in the working directory (vocabulary: revisions, changesets)
History, view and navigate (
log
,log -G
,update
)Calling revisions? Very simple revsets
summary
,diff
Partial commit (
commit path/of/a/directory-or-file
,commit -i
, no Git index!)Local and remote,
push
,pull
,incoming
,outgoing
Evident differences with Git for these simple tasks (Git index,
pull
)
For beginners#
Simple workflows
1 person using different computers and one web repo
Few developers using 1 web repo
First unamed branches + simple merge
Remote new head
Oops simple (
revert
,up --clean
,commit --amend
, notion of phases and publishing repository)Using extensions (example of
hgext.extdiff
(with Meld),shelve
,churn
,graphlog
)
For confortable users#
Advanced workflows and branches
Different needs for “branches”
very short term for developer divergence
short term “feature” branches
long term branches for software versions (3.10, 3.11)
Different technical solutions for “branches”
unamed branches
different repositories
named branches (
branch
command)bookmarks (as Git branches)
topics (lightweight branches that fade away automatically when published, see the topic tutorial )
A bit more on merges (Merge commit are created in the active branch. “Merge my-feature branch into default branch”)
Tags and differences with Git tags
Workflows (Linux, Github, PyPy, Heptapod with topics, …)
hg-git
example how to work on projects hosted on Github/Gitlab,
config and help,
problems, limitations, what can’t be done without Git?,
problems with external tools assuming Git (as pre-commit).
Advanced revsets
bisect
andannotate
/blame
History rewriting (see evolve documentation)
Potential issues and role of phases
Avoid history edition without evolve
obsoleted changesets,
--hidden
evolve extension
commit --amend
,amend
rebase
,absorb
prune
,fold
evolve
histedit
?
For advanced users#
Writting your own extensions
Appendix#
Rust in Mercurial
…