Create empty code-coverage branch and allow custom commit message

[Flamefire]

Use --orphan instead of using the current branchs content and history. Set the commit title in an environment variable and only amend commits with that title to allow for custom commits.

See recent discussion

Before merge I'll delete the branch here to test it

[sdarwin]

The strategy is to always over-write the branch, every time. 1 commit. That is clear and simple and manageable. I don't understand:

git commit -m "$GCOVR_COMMIT_MSG"

without --amend

Its already starting to expand the size of repositories which are using this methodology, but have a different commit message on code-coverage.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (5512491) to head (6ce03c4).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #318   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         3           
  Lines           23        23           
  Branches        10        10           
=========================================
  Hits            23        23           

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5512491...6ce03c4. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Flamefire]

That is clear and simple and manageable.

Strategy now: Usually the last commit is the coverage report. If it is amend. Else it might be unrelated so don't overwrite

Its already starting to expand the size of repositories which are using this methodology, but have a different commit message on code-coverage.

That's why I added a variable to adjust it where desired.

You can only have 1 branch for GH pages, can't you? So if anyone wants to add stuff (or maybe change) their commit will be squashed with the next coverage commit. Works but messy, so this simple check to amend only previously created coverage commits. Not everything.
I just want to be a bit careful when using amend & force push

[sdarwin]

You can only have 1 branch for GH pages, can't you? So if anyone wants to add stuff

Just speculating, this creates a potential scenario

• coverage
• add stuff
• coverage
• add stuff
• coverage
• add stuff

Many commits and the git branch keeps expanding.

How about this: add support for a coverage-permanent branch or github-pages-permanent branch. In the workflow, check if the other branch exists. If it does, as a step, check it out in another directory, copy those files into the code-coverage directory. With that in place, the code-coverage branch can be overwritten each time, and stay at 1 commit which is small and streamlined.

[Flamefire]

Just speculating, this creates a potential scenario

I would rather have that than e.g. "Coverage" - "Custom-commit" being overwritten to "Coverage" - "Coverage"

Many commits and the git branch keeps expanding.

If that really becomes an issue it can be easily resolved with a rebase.

But for now it isn't even clear it ever becomes an issue. So while I like your idea with 2 branches I'd leave that for later when and if required.
If no one ever does another commit to this branch this PR doesn't change anything, it is just safer, isn't it?
Ok, except for a single commit if the branch exists already with another commit title. But even then it could be "fixed" by a one-time manual squash/fixup if that is considered an issue.

[sdarwin]

The "mental model" for this branch, is that it's ephemeral and will be overwritten by the coverage reports. It's dangerous to commit anything to this branch which should be saved. Like saving to your local /tmp directories.

What if the designers of the linux /tmp directory thought "we want to be careful not to lose people's files". And then the /tmp directory as we know it could not exist.

It would be clearer to offer the feature of a "permanent-github-pages" branch, with a name mentioning "permanent".

This feature, as envisioned by Vinnie, was "we overwrite the branch every time, one commit."

If you start making exceptions, and then people depend on that exception, they use this exception, even once, they commit permanent files to the code-coverage branch, the design has become flawed, in my opinion.

The code-coverage branch should be "owned" by the coverage reports. That is way to explain it, and view it. Don't create a loophole, and as soon as that exists, then people rely on it. Compel them to use another "permanent" branch from day-1, if they really need it.

[Flamefire]

This feature, as envisioned by Vinnie, was "we overwrite the branch every time, one commit."

I agree with having, preferably, a single commit for the latest state. However this being git I would also understand having multiple to keep the coverage history as e.g. CodeCov does.

If you start making exceptions, and then people depend on that exception, they use this exception, even once, they commit permanent files to the code-coverage branch, the design has become flawed, in my opinion.

Ok then I'll go YAGNI the other way and change this if and when required.

Reverted to always amend but kept the variable to allow for another commit message in a more visible place. Doesn't hurt IMO and avoids the duplication.

I added 2 sentences in the doc with a summary of what I got out of this discussion and consider useful to know for users of this workflow. Please check if they capture it well enough.

[sdarwin]

Yes, agreed with YAGNI, good idea. Later, if it appears developers need the feature, I hope we can follow something like the strategy I was mentioning.

code review.. the amend flag is missing.

[sdarwin]

Continuing from previous comment, on the topic of "multiple commits".
It should usually happen that all commits are funneled through the pull request process.
Upon request I can add PR previews to any boost repository. That will post coverage information in the PR thread, and the info remains available indefinitely.

An example:

boostorg/json#1145

GCOVR code coverage report https://1145.json.prtest2.cppalliance.org/gcovr/index.html
LCOV code coverage report https://1145.json.prtest2.cppalliance.org/genhtml/index.html
Coverage Diff Report https://1145.json.prtest2.cppalliance.org/diff-report/index.html

Build time: 2026-02-13 17:58:29 UTC

[Flamefire]

code review.. the amend flag is missing.

Uff, thanks for catching that!