We have switched from a custom, manually enforced style guide to using the clang-format tool. Our automated testing now fails with an error for pull requests that don't conform to the new clang-format style - it prints out a diff/patch of the changes necessary to conform with our coding style.

Formatting Your Code

You will need to have clang 3.9 or later installed. If your clang install is from the MOOSE environment package (i.e. the ones downloadable via the links on http://mooseframework.org/getting-started/) and you use Linux, you may need to upgrade to the newest MOOSE environment package version in order for clang-format to be available in your PATH. Many text editors have plugins and support for automatically running clang-format on the files you edit. We recommend using those. For example:

If you wish, you can also install a pre-commit hook that will prevent you from committing changes that don't comply with the new style. To install this hook, run the scripts/install-format-hook.sh script in the MOOSE repository.

You can manually run git clang-format [<commit>] to automatically format files changed since <commit> (or HEAD if omitted). You can also run clang-format -i [<file>...] to update the desired files. We recommend making sure your files comply with the clang-format style on every commit.

Updating In-flight Changes

Changes (pull requests, branches, etc.) that were started before we reformatted our codebase will have a lot of conflicts when attempting to merge into or rebase with the new mainline code. We have provided some tools to aid in this process. First you will need to install a custom git configuration by running (in the main MOOSE repo):


Then make sure ./scripts/clang_format_merge_driver is in your PATH. To rebase a branch onto the newly formatted MOOSE mainline devel branch run the rebase command like normal, e.g.:

git checkout [your-branch]
git checkout devel
git pull upstream devel
git checkout [your-branch]
git rebase devel
... # continue rebase like normal resolving any conflicts

Running a merge like normal will also use the the special clang-format merge driver.

Helpful Emacs Configuration

; Note: This hardcoded path will likely change in the future
; Need to set a variable or copy this file to a new location
(load "/opt/moose/llvm-3.9.0/share/clang/clang-format.el")
(global-set-key [C-M-tab] 'clang-format-region)

(if (null (getenv "MOOSE_DIR"))
    (setq MOOSE_DIR "~/projects/moose")
    (setq MOOSE_DIR (getenv "MOOSE_DIR")))

(setq my-moose-style-path-alist (list (expand-file-name MOOSE_DIR)))

(add-hook 'c++-mode-hook (lambda ()
                    (dolist (path my-moose-style-path-alist)
                  (if (string-match path (buffer-file-name))
                      (add-hook 'before-save-hook 'clang-format-buffer)))))
Current rating: 3


AndyW 1 month ago

This worked for me, with a reasonably up-to-date moose environment package on Mac, but only after I updated emacs from 22.1.1 (which i think comes with MacOSX) to a later version (i chose 25.1.1).

Link | Reply
Currently unrated

AndyW 1 month ago

Drat, i spoke too soon. The C++ mode hook is too eager. If I start emacs with a .C file, and then load a .tex file, it reformats the .tex file upon saving it as if it were C++ code. Help!

Link | Reply
Currently unrated

Cody 1 month ago


I had the same problem at first. The problem was that I had another before-save-hook active lower in my .emacs file to remove trailing whitespace on save. I'm not sure why that mattered but I moved that up above this new configuration and the over-aggressive behavior went away. It doesn't make any sense by that would be the case but it fixed it. Check and see if you have any other active hooks.

Link | Reply
Currently unrated

AndyW 1 month ago

My .emacs contains only what you typed above.

Link | Reply
Currently unrated

AndyW 3 weeks, 5 days ago

I think
(add-hook 'before-save-hook 'clang-format-buffer)
should be replaced by
(add-hook 'before-save-hook 'clang-format-buffer nil 'make-it-local)
Works for me anyway.

Link | Reply
Current rating: 5

AlexL 6 days, 6 hours ago

I get the same undesirable behavior as Andy (haven't tried his fix yet) when putting the clang-formatting logic at the bottom of my .emacs and saving even a .gitignore file in a totally different directory! I'm bamboozled for a variety of reasons...shouldn't this just be a c++ mode save-hook? And shouldn't that lisp logic be matching against the MOOSE path such that I shouldn't see this if I'm in a totally different directory?? Weird.

Link | Reply
Currently unrated

AlexL 6 days, 4 hours ago

+1 for Andy's change

and thanks guys for putting this formatting out there. It's pretty cool stuff.

Link | Reply
Currently unrated

New Comment


required (not published)


R&D 100

Recent Blog Posts

Using our new clang-format Style

1 month, 2 weeks ago

Steady State Algorithm Change

10 months, 3 weeks ago

Making an App inherit from an App

11 months ago

Changing a published API (Deprecation)

11 months, 1 week ago

DiscreteMaterial Objects

1 year, 1 month ago

Recent Posts






RSS / Atom