Plan for the next version of the Mercurial book

Information on how to contribute

• Repository

• Official website

Steps

• Change the license to CC

• Set up a repository and a host for the book

• Get the book to build (instructions could be better)

• Move the text to RST, build with Sphinx

• Move some images to asciidag, others to ascii2svg(?) (ongoing)

• Move the examples to Mercurial tests

• Add content (ONGOING, help always welcome; see https://bitbucket.org/hgbook/hgbook/issues/8/work-out-structure-for-the-book)

  • Scaling chapter (initial draft)

  • Changing history (initial draft)

    • (X) Tie-in with chapter recovering from mistake

  • Templates

  • Revsets

  • Filesets?

  • 'Appendix/Last chapter': future of Mercurial, obsolete, evolve -- possibly reuse

  • Good default configuration (Appendix?)

  • hg-git? (check with durin42; see also Mercurial for Git users(can be used if committed with Gregory Szorcs username))

• Move the book into the Mercurial repository

• Create Dockerfile to build the book easily

• Contact publishers: O'Reilly? No Starch? ... ?

TOC of "An introduction to TortoiseHg+Mercurial", another Mercurial book in Japanese

FYI, this is TOC of "An introduction to TortoiseHg+Mercurial", written by KatsunoriFujiwara in Japanese (published at 2013-02-27).

• part I: for personal use
  • record changes continuously
    • start working on repository (= "hg init")
    • register managed files (= "hg add")
    • record changes of files (= "hg commit")
    • refer recorded revision (= "hg log")
    • refer changes (= "hg diff")

      • refer changes by TortoiseHg

      • refer changes by external GUI tool
  • recover from mistake
    • discard changes in the working directory (= "hg revert")
    • discard the latest revision (= "hg rollback")
    • amend the latest revision (= "hg commit --amend")
  • various operation on files
    • confirm status of all files in the working directory (= "hg status --all")
    • unregister file (= "hg remove/forget")
    • copy or rename file
      • copy file (= "hg copy")
      • rename file (= "hg rename")
      • copy/rename detection after manual operation (= "hg addremove")
    • how revert works on each status file (summarize of previous sections)
    • how limit files in status output
      • ignore files by .hgignore
      • show only specified status files (= "hg status -a/-c/-d/-i/-m/-r/-u")
  • look back recorded information
    • refer history
      • get list of files managed (= "hg manifest")
      • get history related to specified file (= "hg log FILE")
      • follow history beyond copy/rename (= "hg log --follow FILE")
    • refer difference between revisions (= "hg diff -r REV")
    • refer files at specified revision
      • reproduce files at the revision into the working directory (= "hg update")
      • see file at the revision (= "hg cat")
      • get snapshot of files at the revision (= "hg archive")
    • refer source revision of each lines (= "hg annotate")
• part II: for team use
  • interaction between repositories
    • clone repository (= "hg clone")
    • push added revisions
      • confirm revisions to be pushed (= "hg outgoing")
      • push added revisions (= "hg push")
    • pull added revisions
      • confirm revisions to be pulled (= "hg incoming")
      • pull added revisions (= "hg pull")
    • how to specify other repositories
      • register alias (= "[paths]" of .hg/hgrc)
      • how "default"/"default-push" configuration works
    • repository co-operation beyond network
      • via HTTP/HTTPS
      • via SSH
  • merge diverged history
    • what diverged history is
      • divergence in history dag
      • typical usecase of history divergence
    • why merge is needed
    • merge diverged history without conflict (focuses on basic merge flow)
      • configuration for merge tool
      • typical steps to merge diverged history
    • merge diverged history with conflict (focuses on resolving conflict)
      • actual example of changes, which causes conflict
      • typical steps to merge with resolving conflict
  • more detail about merging
    • use external GUI tool
      • use kdiff3

    • resolving conflicts via "resolve conflict" dialog (TortoiseHg specific)

      • operations for un-resolved files
      • operations for resolved files
    • linear merging like CVS/Subversion
      • update to another with uncommitted changes in the working directory
      • updating with uncommitted changes causes implicit merging
    • Mercurial internals
      • why Mercurial should commit merging revision with all files at once
      • why Mercurial should merge revisions, even if they never causes conflict on files (e.g. REV1 adds FILEA, and REV2 adds FILEB)
  • tips for co-operation between repositories
    • push limited revisions (= "hg push" with "-r xxx", "-b BRANCH" and so on)
    • back out published revisions
      • why rollback isn't enough for such purpose
      • steps to back out published revisions (= "hg backout")
  • make history structure readable
    • mark revision by tag
      • steps to mark revision by tag (= "hg tag")
      • how tag information is managed (= .hgtags)
      • conflict of .hgtags at merging
    • named branch
      • steps to create named branch (= "hg branch")
      • push newly created named branch (= "hg push --new-branch")
      • merge with named branch (1st/2nd parents and branch name)
      • close named branch (= "hg commit --close-branch")
  • access restriction and transfer changes under restriction
    • access restriction for repository
      • restriction by OS function (owner, group, R/W permission)
      • restriction by SSH authorized keys
    • transfer changes via various ways (e.g. direct access isn't allowed)
      • use bundle-ed file (= "hg bundle" and "hg unbundle")
      • use export-ed file (= "hg export" and "hg import")
  • portability on various platform
    • character encoding of history meta data
    • filename
      • character encoding of filename
      • case awareness of filename
      • normalization on MacOS/HTFS+
    • contents of managed files
      • end-of-line style
      • encoding of contents
• part III: for advanced use
  • search revisions and files
    • look up by branch name (= "hg log -b BRANCH")
    • look up by revset query
      • look up by meta data (e.g. author(), date() and so on)
      • how to sort result of revset query
      • look up by history structure (e.g. ancestor(), children() and so on)
    • look up by file contents

      • look up file, which contains specified string (TortoiseHg specific)

      • look up revision, of which changes contains specified string (= "hg grep")
    • look up revision by auditing history (= "hg bisect")
      • preparation
      • steps to "hg bisect"
      • widen bisect range at merging revision
  • manipulate history
    • graft (= "hg graft")
      • what grafting is
      • steps to graft
      • how resolve conflicts at grafting
    • rebase (= "hg rebase")
      • what rebasing is
      • steps to rebase
      • how resolve conflicts at rebasing

    • shelve (3rd party one, bundled with TortoiseHg)

      • what shelving is
      • how shelved changes are managed
    • MQ
      • steps of basic usage (= "hg qnew"/"hg qrefresh"/"hg qpop"/"hg qpush")
      • change the revision to be patched
      • patch management
      • importing patch from other than changes in the working directory
      • choose patch hunks
      • more advanced usage (just list up some topics)
  • shadow Mercurial-ing to cooperate with another VCS tool (*1)
  • more advanced topics
    • how to recover from repository corruption
      • dirstate corruption
      • history data corruption (= "hg verify")
    • extensions (comment about bundled extensions)
    • help topics to be read (just listed up)
• appendix
  • installation

    • installation of TortoiseHg

      • on Windows
      • on MacOSX
      • on Linux
    • message localization (locale configuration)
      • on Windows
      • on *nix
  • configuration for Mercurial/TortoiseHg
    • minimum configuration
      • "[ui] username"
      • enabling win32mbcs for filenames using Japanese characters
    • scope of each configuration files
    • how to enable extensions
  • online help
    • refer online help via "hg help"
    • refer online help via "hg serve"
  • how to use SSH
    • preparation on client side
      • on UNIX-like OS
      • on Windows
    • preparation on server side
      • store authorized public keys for hosting services
      • store authorized public keys for ordinary hosts
    • first connection via SSH ("known host" confirmation)
    • confirm existence of "hg" command on server side
    • trouble shooting
  • external merge/diff tools
    • configuration for external tools
      • configuration for tool itself ("[merge-tools]")
      • configuration for tool selection ("[merge-patterns]")
    • how to configure custom tool

(*1) This chapter assumes the case below:

• team wants to use Mercurial internally, but

• team have to use another VCS tool (or can't use any VCS tool :-<) to publish their work, and

• team doesn't want to publish internal work (e.g. each steps of fixing bug)

This chapter shows a example workflow for "hybrid" repository, of which the working directory is managed both by Mercurial and another VCS tool, to ues Mercurial internally.

"hybrid" repository uses named branches to exactly distinguish whether each of revisions comes from inner (= team's work) or outer (= via another VCS tool).