We have an existing code base in Python which doesn't yet use any code formatting tool. Now we have settled on YAPF as a tool and also created its configuration file. To me it is not clear how to reformat the code base without causing havoc in further rebases.

At the moment we rebase everything onto master such that it is a linear history. Some feature branches will need to rebase. This means that all commits in the branch will have to be rebased onto a new master with different formatting. This will likely lead to a lot of merge conflicts in the application of the individual patches.

Git rebase has the option --ignore-whitespace which will likely get us pretty far. But there still may be some issues left over. We will of course try to have the least number of non-master commits around.

Is there some established way to introduce a formatting tool into an existing codebase like this?

  • 1
    Does this answer your question? How to manage a global source code style change?
    – gnat
    Commented Aug 2, 2021 at 13:43
  • 1
    @gnat the other question is about a related but distinct problem. It considers attribution of commits, whereas this question is about merge conflicts and branch management.
    – amon
    Commented Aug 2, 2021 at 13:47
  • 2
    Maybe of help: Retroactively applying Prettier formatting changes to existing branches
    – Doc Brown
    Commented Aug 2, 2021 at 13:56
  • 1
    See also: Formatting A Whole Git Branch
    – Doc Brown
    Commented Aug 2, 2021 at 14:01
  • 1
    Choose a moment at which all branches are either merged back or dead. Then do it all. You will have a discontinuity in your code base that makes it hard to compare code files before and after the style fix but that will be less painful and less costly than the recurring irritations you will get when you do it gradually. Ideally you will have a check in your CI system that won't accept anything not compliant to the settled on style rule set. Commented Aug 2, 2021 at 17:06

2 Answers 2


A few possibilities:

  1. Piecemeal, maybe in an automated fashion: check out a new branch, format a single file, commit, push and create a merge request. At this point there should be minimal interruptions to other people. You could even build in some smarts in the automation, only reformatting files unrelated to any currently ongoing work. In that case you might get away with just a handful of merge requests to reformat everything.
  2. Set aside a time window for formatting all the code in one go. This is obviously the least painful for you, but could be costly depending on what others are doing.
  3. Wait for a merge window to appear organically. Basically, keep polling whether there is any work in progress. If there's none, get your merge request in there and push it through as fast as possible, to minimise disruption. This might work depending on how long your pipeline takes from creating a merge request to actually merging it, and might of course not be feasible if there's always heaps of ongoing work.

So the situation is that any file touched by your code formatted will look very much different after it is formatted. And that will make diffs between “before” and “after” files painful.

First thing, you check that your formatting tool is consistent. I’ve seen tools that switched between two states every time it would format code! If that’s the case, throw the tool away, never let it touch your code.

Second thing, take an existing file, make a trivial change plus reformatting. Try a diff. Are you wasting lots of time? Did you find the trivial change? If you wasted lots of time, worse, if you couldn’t spot real changes, think very hard.

You might have a rule that formatting changes must not be mixed with other changes. Ever. If you want to edit files A, B and C, you first make a pull request for “reformat A, B and C using the new tool”. And when that’s reviewed , you do your actual work.

And maybe you should think what all this is good for. Does it actually benefit you? If there’s no benefit, then don’t do it. Or only if it changes adherence to a policy from 95% to 100%. And in that case, only if the 100% is actually an improvement.

  • 1
    Sure, it will cause long diffs, but these commits can be ignored in git blame. The problem is that there isn't a policy until now, so all the code looks inconsistent. And it seems to annoy enough developers that we have asked for this change. In total I think that introducing the formatter is worth it. Commented Aug 3, 2021 at 7:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.