Bitcoin core 0.11.2 (bitcoind –help) prints the following:
-blocknotify=<cmd> Execute command when the best block changes (%s in cmd is replaced by block hash)
Neither in the Bitcoin wiki nor elsewhere ‘best block’ is mentioned. I would suggest to give a hint, what that is and to give an example why someone would want to be notified about the change of it.
It seems to be in a complete other category than ‘alertnotify’ option, which, I guess, everyone would like to receive.
The best block is the current “head” of the block chain. It is the chain with highest cumulative Proof-of-Work. You’d set this if you want to be notified of new blocks.
Feel free to reword this into something better, but it’s easy to lose the subtle meaning (e.g., “the longest chain” won’t do - there may be a shorter chain with more work in it).
I disagree that best block should be defined in the help text since it’s difficult to succinctly summarise, it should be a well-understood term, and we shouldn’t add the same definition in many places.
In fact, it’s already incorrectly defined in the getbestblockhash RPC as “Returns the hash of the best (tip) block in the longest blockchain.” That’s wrong, since the best block is the tip of the chain with the most work, not the tip of the longest chain.
It’d be far better to make sure that best block is correctly defined at https://bitcoin.org/en/developer-documentation.