[quacker]

Using git history as documentation is hacky. A majority of feature branch commit messages aren't useful ("fix test case X", "fix typo", etc), especially when you are accepting external contributions. IF I wanted to use git history as a form of documentation (I don't. I want real documentation pages), I'd want the history curated into meaningful commits with descriptive commit messages, and squash merging is a great way to achieve that. Git bisect is not the only thing I do with git history after all.

And if I'm using GitHub/Gitlab, I have pull requests that I can look back on which basically retain everything I want from a feature branch and more (like peer review discussion, links to passing CI tests, etc). Using the Github squash merge approach, every commit in the main branch refers back to a pull request, which makes this super nice.

[OkayPhysicist]

As far as I'm concerned, the git history of a project is the root source of truth of why a change was made, at that point in time. External documentation is mostly broad strokes, API references, or out of date. Code comments need to be git blamed anyway to figure out when they were added, and probably don't exist for every little change. Pull requests associated with a given commit give the broad description of "what feature was being implemented or bug was being fixed" for a given change, but a commit message tells me what, specifically, during that work, triggered this particular change. I want to know, for example, that the reason this url gets a random value appended to it is that while implementing a new page to the site it was found that the caching service would serve out-of date versions of some iframe. It never made it out of dev testing, so it never became a full-blown bug, it wasn't the purpose of the feature branch, so it wasn't discussed in the PR. But the commit message of "Add some cache-busting to iframe" (even something that brief), can go wonders to explaining why some oddity exists.

[quacker]

Agree to disagree I guess, but IME, git history is good for low level detail, not for high level information. Git history is a poor source for understanding architecture, code organization, and other aspects of the codebase. More often, git commit messages tell me what changed - not why the change was made or who it impacted or etc.

Reading through git history should be my last resort to figure something out about the codebase. Important knowledge should be written somewhere current (comments, dev docs, etc). If there is a random value being appended to a url, at least a code comment explaining why so I don’t even have to git blame it. Yes, these sources of knowledge take some effort to maintain and sure, if I have a close-knit team on a smaller codebase, then git history could suffice. But larger, long-lived codebases with 100s of contributors over time? There’s just no possible way git history is good enough. I can’t ask new team members to read through thousands of commits to onboard and become proficient in the codebase (and certainly not 5x-10x that number of commits, if we are not squashing/rebasing feature branches into main. Although, maybe now an LLM can explain everything). So I really need good internal/dev documentation anyway, and I want useful git history but don’t care so much about preserving every tiny typo or formatting or other commit from every past feature branch.

Also iirc, with github, when I squash merge via the UI, I get a single squashed commit on main and I can rewrite the commit message with all the detail I like. The PR forever retains the commit history of the feature branch from before the squash, so I still have that feature branch history when I need it later (I rarely do) so I see no reason to clutter up history on main with the yucky feature branch history. And if I tend toward smaller PRs, which is so much nicer for dev velocity anyway, even squashed commits can be granular enough for things like bisect, blame, and so on.