What does the -r option of Git log do?

Question

The man page git-log(1) says:

-r
Show recursive diffs.

So we can put this question in another way:

What is meant by "recursive diffs" in this context.

After getting this answer from @phd, I did some tests that aim in the indicated direction:

If I execute the following commands in a current version of the Git source repository (recently cloned from https://github.com/git/git.git) with checked out master (currently pointing to commit 6a6c0f1), they give identical output:

git log --name-only -m
git log --name-only -m -r

(For this to work, one might have to increase the diff.renameLimit to round about 3150.) I tried this with Git versions 2.10.2 and 2.17.1 obtaining equal results.

In addition, the command

git log --name-only -m master~..master

outputs

commit 6a6c0f10a70a6eb101c213b09ae82a9cad252743
Author: Junio C Hamano <[email protected]>
Date:   Thu May 9 00:37:54 2019 +0900

    The eighth batch

    Signed-off-by: Junio C Hamano <[email protected]>

Documentation/RelNotes/2.22.0.txt

from the last line of which one can see that this command looks into subdirectories even without -r.

Gangrel

Along similar lines, the -m, -c, and --cc options have their documentation in the diff doc text files whcih are included from both git log and git show documentation files. But the front-end log and show commands set the default values of these options quite differently. If you merely read the docs, you'll have the impression that git log will default to showing a combined diff for a merge, but in fact git log defaults to not showing any diff (git show defaults to a combined diff). – Reiser

Answer 1

The option comes from git diff-tree docs and in git diff-tree it really works; see this example:

$ git diff-tree master~ master
:100644 100644 a2be0e5e5959396fb85445cfff714d7b04a1231b 5d7a2a0a4fd6fbaf439aa08bb7f17052a65a5236 M  ANNOUNCE
:100644 100644 22e746900ab77a79b4cb6780f536a517771fe276 f2aae0e9c7c87226f4f5c06ca006f4d04ce79dc1 M  ChangeLog
:040000 040000 54ef4d981c00162085347031d31286d630258153 76d21516ed54422a8981a31a9a0bf47dc5e5af6f M  mimedecode

$ git diff-tree -r master~ master
:100644 100644 a2be0e5e5959396fb85445cfff714d7b04a1231b 5d7a2a0a4fd6fbaf439aa08bb7f17052a65a5236 M  ANNOUNCE
:100644 100644 22e746900ab77a79b4cb6780f536a517771fe276 f2aae0e9c7c87226f4f5c06ca006f4d04ce79dc1 M  ChangeLog
:100644 100644 4ca2f25d2d061dba16294d67ab8018ea00be2b37 ead1ab38493c7e5119d8204a8731747cc534647c M  mimedecode/mimedecode.py

The option is included in docs at git-diff-tree.txt and the file is included in git-log.txt via diff-options.txt.

I suspect the inclusion of the option in git log docs is an artifact of doc generation. At least I cannot make the option works for me in git log.

Tholos

Thank you, @phd, for your fast and enlightening answer. Playing around with git log -r in the Git source repository, I could not see any effect of that option either. I supplemented this in the question. – Metaphysics

In fact, this is a general problem with Git documentation (and Git commands): they share sources and therefore options can be supplied that wind up having no effect, and/or are documented that have no effect or—in some cases where the documentation factorization was unwise, though I think most of these have been fixed over time—are actually rejected by the command. – Reiser

It has been removed from git-log documentation github.com/git/git/commit/… – Calomel