Improve legibility of code history before 2012

[barijaona]

This discussion replaces #2011

The problem

Ever since I started trying understand Vienna's code, "played around" with Xcode and learned how to use Git (my first commit was in January 2012), I have been annoyed by some changes that occurred during the second half of year 2011.

Vienna's history has been marked by the succession of various version control systems: CVS, then SVN and currently Git.

Historically, the disk layout was : a folder per branch. So, in June 2011, we had 7 folders, numbered 2.0.0, 2.1.0… up to 2.6.0.

When we look back at this, some drawbacks of this situation become apparent: although 2.3.0 inherits from 2.2.0, finding out when and how they diverged is not always evident. To try to guess the purpose of the new branch and understand its timing, we can use commands like:

git log --reverse --format='%h %as %aN %s' --date=short -- 2.2.0 
git log --reverse --format='%h %as %aN %s' --date=short -- 2.3.0

However, commands like git blame fba5e0fe 2.3.0/AppController.m provide no information prior to the start of version 2.3.0.

A particular case is 2.4.0. The output of:

git log --reverse --format='%h %as %aN %s' --date=short -- 2.4.0

is not really helpful.

Similarly, if you run git blame Vienna/Sources/Application/AppController.m today, you won't see anything prior to August 2011.
Why? Because the repository got completely empty at some point.

The workaround

Through some combinations of backdated giv mv, git cp, git merge and sometimes git cherry-pick, I created temporary branches that bypass the problematic situations.

I then used git replace --graft <child-commit> <new-'foster-parent'> to induce git to retrieve the rectified history when the user runs git log or git blame.

Once I was satisfied, I created (also backdated) tag objects in order to make the changes more visible and ensure they won't disappear from my repository.

The table below summarizes the changes and why they were needed:

Child commit	Original parent(s)	New parent (added tag)	Comment
91405bb	0c27f93	repl/0c27f93b-s2.1	Start of branch 2.1.0
ac729c8	e95db50	repl/e95db507-s2.2	Start of branch 2.2.0
f64b09f	6950eda	repl/6950edad-s2.3	Start of branch 2.3.0
30dc292	8d54ae0	repl/8d54ae01-s2.5	Start of branch 2.5.0
f12fb59	6d838c5	repl/6d838c50-t2.4	Late re-attachment of branch 2.4.0 to trunk
049c4b6	b3fd343	repl/b3fd343a-s2.6	Start of branch 2.6.0
205e196	c9e39d7	repl/c9e39d77-p2.6.0.2600	Move content of 2.6.0 to root and cleanup other branches
cd1091f	9ff5799 76d2a5b	repl/9ff5799f	Merge work from Adam Hartford

The limits

git replace creates refs under refs/replace/* in `.git.

Github will store these replacement references if you explicitly push them, but when viewing commits, diffs, or history, Github's web interface does not honor or expose replace refs. Gitlab and Forgejo/Codeberg behave similarly.

You will therefore only be able to view the changes in your local repository, using supporting tools (such as git command line, GitX or tig), after explicitly fetching the replacements:

git fetch --tags --prune --prune-tags <my-repo>
git fetch <my-repo> '+refs/replace/*:refs/replace/*' 

My intent

After one week or two, I plan to:

• push the replacements to Vienna's main repository : git push ViennaRSS 'refs/replace/*'
• push the corresponding repl/* tags
• delete the 2.0.0 to 2.6.0 tags that were used to safeguard the previous history

[matthewruzzi]

I am assuming that it is not a good idea to force push overwrite all of the old history.

[barijaona]

There is no force push overwrite at all here.
There is a push of supplementary commits, but these will not cause any change, unless the user pulls the replacement references. That remains completely optional and can be easily undone (git replace -d) at any time.

The only "destructive" change is the removal of the 2.0.0 to 2.6.0 tags that were created in August 2011. I went this way in order to limit the number of branches presenting redundant information. Since the history is already retraced in the trunk, these tags unnecessarily clutter the graphs.

My only regret at this point is that branch 2.4 (which was active from September 20, 2009, to January 12, 2010) was retroactively integrated into the trunk (on January 18, 2010). To avoid clutter, I ended up having this retraced as c90c7ef..0eb8c6e, instead of 73e52a4..15ea49e currently in ViennaRSS. This is not ideal, but given that these references aren't the originals (at that time, the version control system was SVN, not Git), and that they are only mentioned in this single discussion, I think we can live with it.

[barijaona]

`git bundle ˋ can be used to backup the tags (especially 2.4.0) before deletion.