Add recommended hgrc

hgrc

 # This .hgrc is recommended for working on the Adblock Plus project.

[Wladimir Palant, 2016/02/20 17:50:48]

General notes:

1) The order is wrong, obvious stuff ([ui], [defaults]) should go first,
extensions and extension settings should be listed after that.

2) An essential setting is missing:

[diff]
git = true

Without this Mercurial won't produce binary diffs.

[Felix Dahlke, 2016/02/20 20:16:38]

Don't feel nearly as strong about that, changed it.
Added. Not sure how I got by without that so far.

 #
 # When using this as your .hgrc as-is, it provides a nicer user interface and
-# enables some extensions that are useful for working on any project.
+# enables some extensions that are useful for working on pretty much any
+# project.
 #
-# The commented parts are more specific to the Adblock Plus project and might
-# not make sense if you also work on other Mercurial projects. Have a look and
-# decide for yourself what you want to enable. When you are not working on any
-# other projects using Mercurial, it is recommended that you uncomment
-# everything.
+# The commented parts either do not work on all systems, are a matter of taste,
+# or specific to the Adblock Plus project and might not make sense for everyone.
+# Have a good look and decide for yourself what you want to enable.
 
-# Extensions
+## User interface controls
+[ui]
+
+# Sets your global user name. If you do not uncomment this, you will have to
+# set it on a per-repository basis.
+#username = Jane Doe <jdoe@example.com>
+
+## Diff (i.e. patch) format configuration
+[diff]
+
+# We use Git's extended diff format which includes more information (such as
+# changes to binary files).
+git = true
+
+# Makes diff output include eight lines of context.
+unified = 8
+
+## Defaults
+#
+# These change the default behaviour of common Mercurial commands.
+[defaults]
+
+# `hg log` shows the history of all branches by default, not just that of the
+# current branch. The `--graph` option shows this as an ASCII tree and marks
+# the revision you are currently at, which makes the history a lot easier to
+# read.
+log = --graph
+
+# The "master" bookmark
+#
+# Most repositories of the Adblock Plus project use bookmarked branches to track
+# multiple lines of development. The bookmark for the main line of development
+# is, by convention, called "master".
+#
+# Unless you are working with Mercurial repositories that do not have a "master"
+# bookmark, it is recommended that you uncomment the following defaults.
+
+# `hg clone` updates to the latest changeset on the default branch. When working
+# with repositories that have a "master" branch, you will want to update to that
+# one instead, which you can do by adding `--updaterev master`. By uncommenting
+# the following line, you won't have to worry about that. Note that when
+# enabling this, you can still update to the latest changeset in the default
+# branch by specifying `--updaterev default`.
+#clone = --updaterev master
+
+# `hg push` and `hg outgoing` will by default include all changesets, including
+# bookmarked branches that you might want to just keep locally. To avoid this,
+# you need to add `--rev master`. By uncommenting the following two lines, you
+# won't have to worry about that. Note that when enabling this, you can still
+# push any branch by specifying the `--rev` option.
+#push = --rev master
+#outgoing = --rev master
+
+## Extensions
 #
 # Mercurial is, out of the box, fairly minimal. A lot of useful functionality
 # comes as extensions. Most of the useful extensions are even part of the
 # default Mercurial distribution, but not enabled by default.
 [extensions]
 
-# Pager extension, shows the output of commands like `hg log` in a pager.
-pager =

[Wladimir Palant, 2016/02/20 17:50:48]

I don't use that, find it pretty annoying actually and would love to disable in
Git - my terminal has scrollback. I don't think such extensions which are really
a matter of taste belong here, maybe as recommendation for something to look at.

Nit: "shows in a pager" doesn't actually explain anything. Maybe "shows the
output page by page"?

[Felix Dahlke, 2016/02/20 20:16:38]

Hm, didn't think anyone would not want that. So you always specify `-l` I
suppose? Made it opt-in then.
I think it does explain this adequately, a terminal pager is a thing. I've
clarified this a bit more.

[Wladimir Palant, 2016/02/22 11:05:26]

Yes, I have "log = -l 5" set under [defaults].

-
-# Color extension, colours the output of commands lke `hg log`.
-color =

[Wladimir Palant, 2016/02/20 17:50:48]

Same here. While this is usually useful, it produces a horrible mess on Windows.

Nits: colours => colors (we generally use AE), lke => like

[Felix Dahlke, 2016/02/20 20:16:38]

Done.

-
-# Progress extension, shows an ASCII progress bar for operations that take,
+# Progress extension, shows an ASCII progress bar for operations that take
 # longer.

[Wladimir Palant, 2016/02/20 17:50:48]

No comma after take.

[Felix Dahlke, 2016/02/20 20:16:39]

Done.

 progress =
 
-# Rebase extension, provides the `hg rebase` command, see:
-# https://www.mercurial-scm.org/wiki/RebaseExtension
-rebase =
+# Color extension, colors the output of commands like `hg log`. Enable it if
+# your terminal supports colors (assuming you like colors).
+#color =
+
+# Pager extension, shows the output of commands like `hg log` in the terminal
+# pager (e.g. less) configured below in the [pager] section.
+#pager =
 
 # Record extension, provides the `hg record` command that allows you to make
 # partial commits.
 record =
 
-# Purge extension, provides the `hg purge` (aliased to `hg clean` command that
-# allows you to clean unversioned files.

[Wladimir Palant, 2016/02/20 17:50:48]

Nit: You need to close that parenthesis somewhere.

[Felix Dahlke, 2016/02/20 20:16:38]

Done.

+# Purge extension, provides the `hg purge` (aliased to `hg clean`) command that
+# allows you to remove unversioned files.
 purge =
 
-# Shelve extension, provides the `hg shelve` command that allows you to set
-# pending changes aside, see:
-# https://www.mercurial-scm.org/wiki/ShelveExtension
-shelve =

[Wladimir Palant, 2016/02/20 17:50:48]

I couldn't find any use for that when working with bookmarked branches.

[Felix Dahlke, 2016/02/20 20:16:39]

Not? I use it on a weekly basis, just like git stash. I don't always want to
make a new branch out of my WIP changes when just quickly fixing a typo or
something. Plus, it's more beginner friendly. No particularly strong opinion
about not enabling it by default, but I don't think one extra command hurts. Not
everyone will use histedit or record, either.

+# Rebase extension, provides the `hg rebase` command, see:
+# https://www.mercurial-scm.org/wiki/RebaseExtension
+rebase =
 
 # Strip extension, provides the `hg strip` command that allows you to remove
 # existing changesets.
 strip =
 
 # Histedit extension. Provides the `hg histedit` command that allows you to
 # change and merge existing changesets, see:
 # https://www.mercurial-scm.org/wiki/HisteditExtension
 histedit =
 
-# Configuration for the pager extension, see above.
+# Shelve extension, provides the `hg shelve` command that allows you to set
+# pending changes aside, see:
+# https://www.mercurial-scm.org/wiki/ShelveExtension
+shelve =
+
+# Configuration for the pager extension. This doesn't have any effect unless
+# you enable the pager extension above.
 [pager]
 pager = LESS='FSRX' less
-
-# User interface controls
-[ui]
-# Sets your global user name. If you do not uncomment this, you will have to
-# set it on a per-repository basis.
-#username = Jane Bloggs <jane@adblockplus.org>

[Wladimir Palant, 2016/02/20 17:50:48]

I hope we never hire a Jane...

The explanation is rather strange. I think the second sentence should rather be:
"You have to set this or all your commits will show up with a weird
auto-generated author name."

[Felix Dahlke, 2016/02/20 20:16:38]

Is that what happens for you? I always get this:

$ hg init foo
$ cd foo
$ touch bar
$ hg add bar
$ hg commit -m "Initial commit"
abort: no username supplied
(use "hg config --edit" to set your username)

(Yes, I do not have username in ~/.hgrc, I'm working on non-ABP Mercurial
projects.)

[Wladimir Palant, 2016/02/22 11:05:26]

Weird, same here - supposedly working like that since at least 2007
(https://www.selenic.com/hg/rev/78a0dd93db0b). I could verify that on Windows
and OS X. Yet I'm certain that not too long ago someone again managed to push
commits with a misconfigured user name... And I've seen that issue myself, yet I
started using Mercurial after 2007.

-
-# Aliases
-#
-# These change the default behaviour of common Mercurial commands.
-[alias]

[Felix Dahlke, 2016/02/20 12:01:37]

Any other suggestions for useful aliases I couldn't think of?

Note that I haven't added the `update` -> `update -r master` alias you suggested
because I still want to investigate if there really is no difference between `hg
update` and `hg update -r default` - I think there is.

-
-# `hg log` shows the history of all branches by default, not just that of the
-# current branch. The `--graph` option shows this as an ASCII tree, which makes
-# the history a lot easier to read.
-log = log --graph
-
-# `hg clone` updates to the tip by default, which is just the latest changeset,
-# on any branch. You most likely want to update to the "master" bookmark
-# instead, which you can do by adding `--updaterev master`. By uncommenting the
-# following alias, you won't have to worry about that:
-#clone = clone --updaterev master
-
-# `hg push` will by default attempt to push all changesets, including bookmarked
-# branches that you might want to just keep locally. To avoid this, you need to
-# add `--rev master`. By uncommenting the following alias, you won't have to
-# worry about that:
-#push = push --rev master

[Wladimir Palant, 2016/02/20 17:50:47]

You are misusing aliases here, you should use [defaults] section instead:

[defaults]
log = --graph
clone = --updaterev master
push = --rev master
outgoing = --rev master

Note that I added outgoing, I forgot this one before.

[Felix Dahlke, 2016/02/20 20:16:38]

Oh nice, forgot that that's possible. Using aliases for this seemed hacky. (Yes,
I do not have any defaults or aliases currently.)

Done.