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#

  • About revision control

  • 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#

  • Handling files in Mercurial

  • 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

  • templates

  • Merges

  • bisect and annotate/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?

  • Hooks

For advanced users#

Appendix#