I'm developing a software library that I began during my PhD and used in my thesis. I've since started a research position and, as an experiment, I wanted to try rewriting parts to see if I could simplify it. This turned out to be way more successful than I expected. I rewrote years of work in a matter of weeks, and the end result is much cleaner than what I had before.

Now I want to make my rewrite public, but I'm not sure what to do about the revision history. I reference specific commits in the old version in my thesis, so I'd like to have those preserved for posterity (and so I can laugh at my junk code later.) I can think of 3 options:

  1. Delete all the old code in one commit. Extract all the commits from the rewrite as patches and apply them one-by-one to the old repository.
  2. Make a tag branch for the old code, say my-lib-0.0.1, explaining that it was a nascent version of the code from when I was young and foolish. Add the rewrite as a remote for the old code, then git reset --hard rewrite/master. This will replace the revision history of the old code with that of the rewrite.
  3. Explain in the README for the old repo that it's deprecated, and keep the rewrite in an entirely new repo.

I don't like option 3, as I'd rather have everything in the same repository. Additionally, there is still a fair amount of shared code between the old and new versions. Option 2 has the virtue of keeping the revision history looking fairly clean (users won't have to clone 400+ commits of garbage from when I didn't know what I was doing) but keeping the history there in the unlikely event that someone does want to see it. On the other hand, I don't like the idea of "rewriting history", and to avoid cloning garbage commits I can always tell people to do shallow clones.

Which of these options is the least bad? Are there others that I haven't considered?

  • Two questions: (1) Is there any chance you will need to maintain the old version, e.g. someone important happened to be using it and would like some bug fixes, and doesn't want to upgrade to the new version? and (2) If so, is there any chance you would want to be able to merge those changes into the new version at some point?
    – John Wu
    May 11, 2017 at 19:41
  • Are you the only committer? May 11, 2017 at 19:45
  • @JohnWu I won't need to make bug fixes to the old version; it's alpha code anyway. May 11, 2017 at 20:24
  • @RobertHarvey I'm the only committer, so it's not as if burying the old code would be inconsiderate to any contributors. May 11, 2017 at 20:31
  • 2
    Absent any other committers, it's unclear what value (if any) all that history would have for anyone else. May 11, 2017 at 20:32

1 Answer 1


This is very typical situation in software development.

In my view, you should first tag the final version of your old code (no need to branch as you can always branch from the tag if needed). Also, the rewriting takes place incrementally and this means you commit changes gradually. When you reach your new version you tag again and so on. In every release (tagging) you include a release notes document.

What you may come across, though, are code braking changes. In this case, you communicate them by altering the version number and the release notes.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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