User Tools

Site Tools


doxygen

This is a short guide of how to rebase a PR or branch that was created (and based on a commit) before the Doxygen change but now needs to be rebased onto the current master.

The problem is that any comments you've modified or added will be in the wrong style. The approach described below means your comments will appear in git history to have always been Doxygen and should avoid hairy merges of modified comments.

The “magic” approach involves setting up a custom merge driver in git. For each merge conflict it runs the reformatting script on all 3 parts of the merge (local, remote, ancestor) before attempting the merge. This should allow for rebase action that is no more complex that it would be without the Doxygen change. This will overwrite files without warning, so proceed with caution (i.e. back up your branch).

Set up the merge driver

The conversion is automated using a set of scripts that can be found on the most recent master version of cbmc, in the scripts folder:

Assuming you have the CBMC repository set as the remote origin, you can run the following command from the scripts folder to get the scripts:

git checkout origin/master -- reformat_docs.py do_doc_convert.py doxy_merge_driver.sh

Now, rename these scripts so that they don't clash with the checked-in versions during the rebase/merge. You may append a single underscore to the end of each filename, for example.

You will also need to modify the contents of your renamed doxy_merge_driver.sh script so that it calls the renamed reformat_docs.py.

The modified merge driver (doxy_merge_driver_.sh) must be configured in a .gitconfig of your choosing (e.g. the one in your home directory). Add this entry to it:

[merge "doxy_merge_driver_"]
  name = doxy_merge_driver_
  driver = scripts/doxy_merge_driver_.sh %A %O %B

Finally you need to tell git to use this merge driver. You can do this by modifying the .gitattributes. For the .cpp and .h entries, add a merge rule:

*.cpp text merge=doxy_merge_driver_
*.h text merge=doxy_merge_driver_

You''ll need to change the copy in your local git repository, commit it, and move it to the start of the rebase (I'll explain once we get there).

Doing the rebase

You are now set to do the rebase. Back up your branch before proceeding.

git rebase -i master

If you modified and committed your .gitattributes you need to pick that commit to the top of the todo list (so that it is at the beginning of the rebase history).

Then just hit go. Any merge conflicts should just be real conflicts at this stage.

doxygen.txt · Last modified: 2017/08/11 18:07 by mbrain