Add recommended hgrc

hgrc

 # This .hgrc is recommended for working on the Adblock Plus project.
 #
 # When using this as your .hgrc as-is, it provides a nicer user interface and
 # enables some extensions that are useful for working on pretty much any
 # project.
 #
-# The commented parts do either not work on all systems, are a matter of taste,

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

do either => either do

[Felix Dahlke, 2016/02/22 22:16:53]

Done.

+# 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.
 
 ## 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 ue Git's extended diff format which includes more information (such as

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

ue => use

[Felix Dahlke, 2016/02/22 22:16:53]

Done.

+# We use Git's extended diff format which includes more information (such as
 # changes to binary files).
 git = true

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

Might want to add the following:

# Uncomment this if you want to see more than three lines of context on your
# patches. Eight lines generally allow a better overview.
#unified = 8

[Felix Dahlke, 2016/02/22 22:16:53]

Done. Made it a default since I believe it's saner than three lines of context.

+
+# 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, which makes
-# the history a lot easier to read.

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

How about adding: It will also mark the revision you are currently at.

[Felix Dahlke, 2016/02/22 22:16:53]

Done.

+# 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 "tip" by default, which is just the latest changeset, on
-# any branch. You most likely want to update to the "master" bookmark instead,

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

This isn't correct - hg clone updates to the latest commit on the default
branch, it doesn't update to other named branches.

You might want to add that specifying "hg clone --updaterev default" explicitly
will restore the default behavior regardless of this setting.

[Felix Dahlke, 2016/02/22 22:16:53]

Oh indeed, I was pretty sure it would update to tip...
 
Done.

-# which you can do by adding `--updaterev master`. By uncommenting the following
-# line, you won't have to worry about that:
+# `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

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

Here as well, you can say that one can always specify --rev my-bookmark
explicitly to override this default and push a different branch.

[Felix Dahlke, 2016/02/22 22:16:53]

Done.

-# won't have to worry about that:
+# 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
 

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

So, what about update? I checked and there are two differences between "hg
update" and "hg update -r default". First, the former will only update on a
linear history. If you are on a different anonymous branch than the head of the
default branch it will abort. This will save you in many cases.

The second difference is the really critical one - hg update without a revision
will automatically move bookmarks. Consider the following history:

o  	* Bar [issue-12345]
|
@  	* Foo [master]
|
o  	* Initial commit

You've been working on the feature branch issue-12345, later you did "hg update
-r master" to go back to the master bookmark. If you use "hg update" now and
forget to specify an explicit revision you won't merely be moved to your feature
branch, it will also move the master bookmark there! It's not a theoretical
scenario but rather exactly the situation I have in adblockpluscore with the
emscripten branch right now (and I actually had to fix the master bookmark
already).

IMHO that logic is quite a footgun, I don't really understand what they were
thinking with the implicit moving of bookmarks on update. "update = --rev
master" here will take care of that. And "hg update --rev default" will give you
the default logic again - albeit without the bookmark moving behavior (a good
thing IMHO) and crossing branches (fine as there are no side-effects).

So I'd be very much in favor of adding this as a recommendation here.

[Felix Dahlke, 2016/02/22 22:16:53]

Yes me too, we're both pretty used to Mercurial by now and we had no idea how
`hg update` works.

I had this all added. For the record, I did it like this:

----------
# `hg update`, when used without arguments, has somewhat questionable behaviour.
# It will update the working directory to the head of the current branch, and
# move the active bookmark while at it. We believe it is less error prone if
# running `hg update` without rev updates to the main branch instead.
update = --rev default
# With the above, you will still need to specify `--rev master` when working
# with repositories that have a "master" branch. If you uncomment the following
# instead, you won't have to worry about that.
#update = --rev master
----------

BUT:

----------
$ hg update feature
abort: please specify just one revision
----------

As we both know, --rev is optional. Most documentation I've seen doesn't specify
the option, nor do I use it in practice. Seems that when --rev is not specified,
Mercurial doesn't overwrite the default and adds it redundantly instead...

That makes me not want to add this default. The error message is too cryptic and
it's too inconvenient.

[Wladimir Palant, 2016/02/23 10:52:18]

Ouch... As you probably noticed, I always specify the -r parameter - I don't
want to remember that for hg update it is optional but for hg revert it is not.
But well, then we just have to make sure that we explain this behavior
somewhere.

[Felix Dahlke, 2016/02/23 16:31:38]

Yeah, my vote is for getting started. Wanna add that?

 ## 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]
 
 # Progress extension, shows an ASCII progress bar for operations that take
 # longer.
 progress =
@@ skipping 29 matching lines @@
 
 # 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