Wondering why `diff-cover` uses three dot notation for the diff

Hi,

We have integrated diff-cover into our workflow at work by making jobs publish diff-cover comments into the PR for a branch, including links and emojis (we use BitBucket Server).

Works great, here’s a quick screenshot:

So thanks a lot for the great tool!

---

Now I would like to describe a problem we are having, and later discuss a couple of possible solutions.

On occasion we work with long lived topic branches. Those are topic branches which will be around for some time (say a month) while a large feature is being worked on. From those long lived topic branches we then create short lived topic branches for smaller amounts of work (for example, a short lived branch to work on the application business logic, then another one after that to work on the GUI, and so on). Then we open PRs to merge the short lived branches into the long lived one.

It happens that we want to get some update from master in both the long lived branch and into its short lived branches. Those changes that come from master won’t appear in the PR from short topic -> long topic, as BitBucket will only show the changes that are in short topic and not on long topic, even if they came from somewhere else.

And here we noticed a problem: a few files are being reported as not being fully covered by diff-cover, but they are not even shown in our tree of “changed files” on the PR in BitBucket: it is the case with the test_grid_table_editor.py in the previous screenshot. This is confusing as we don’t really know what to do to fix the coverage, as the file is not even visible to us on the PR.

Digging into the code, I noticed diff-cover uses three-dot range notation to obtain the patch for the PR.

When using the three dot notation, the commit history is taken in account to produce the patch, including commits which are in both branches but are not in the actual patch that will be applied by the merge.

The other common notation used with git diff is two-dot range notation, which only shows the full patch between the two branch tips: a plain diff between the trees, regardless of the commit history.

Another way to explain this:

1. Branch long is created from master.
2. Branch short is created from long.
3. A new function, with 0% code coverage, is committed to master into commit ABAB.
4. master is merged into long and short, so both branches now contain the commit ABAB.

With two-dot notation, the code coverage for the short -> long merge shows nothing (that’s the exact patch between them).

With three-dot notation, the code coverage for the short -> long merge will show the function with 0% coverage, even thought it was not added by the developers of either long or short branches, coming from master (of course it should have been covered in the first place, but that’s beside the point).

IMHO the two-dot notation makes more sense for diff-cover, this way developers only worry about the actual lines being changed by them (which codecov.io calls “patch coverage”), which I believe is one of the selling points of using diff-cover. 😁

---

Having said all that (and sorry about the long post), I see some solutions:

1. Change diff-cover to use two-dot notation. This is simplest, but I’m not sure how workflow works, and it would break use cases where the diff-cover notation makes sense.
2. Make a --diff-notation=two/three (or similar) option that lets the (advanced) user choose which method to use to obtain the patch.
3. Restart the work in #26 and let the user provide a patch file, bypassing the actual call to git diff.

What do you guys think? I’m happy to contribute a PR with whatever solution you deem best.

Thanks!

[wedaly]

I don’t remember either 😃 I suspect that I just knew less about git at the time, and the three-dot notation worked for the way we did branching at EdX.

[nicoddemus]

cc @gcardozo123