docs: explain why squash merges are broken with long-running branches

In many projects, squash merges are commonly used, primarily to keep a tidy history in the face of developers who do not use logically independent, bisectable commits. As common as this is, this tends to cause significant problems when squash merges are used to merge long-running branches due to the lack of any new merge bases. Even very experienced developers may make this mistake, so let's add a FAQ entry explaining why this is problematic and explaining that regular merge commits should be used to merge two long-running branches. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

brian m. carlson committed Sep 20, 2020 at 23:22 UTC 5065ce412ef083a02288c1972ea3d07423cace0e

1 file changed +32

Documentation/gitfaq.txt

+32

@@ -241,6 +241,38 @@ How do I know if I want to do a fetch or a pull?::

241 ignore the upstream changes. A pull consists of a fetch followed

242 immediately by either a merge or rebase. See linkgit:git-pull[1].

243

244 +Merging and Rebasing

245 +--------------------

246 +

247 +[[long-running-squash-merge]]

248 +What kinds of problems can occur when merging long-lived branches with squash merges?::

249 + In general, there are a variety of problems that can occur when using squash

250 + merges to merge two branches multiple times. These can include seeing extra

251 + commits in `git log` output, with a GUI, or when using the `...` notation to

252 + express a range, as well as the possibility of needing to re-resolve conflicts

253 + again and again.

254 ++

255 +When Git does a normal merge between two branches, it considers exactly three

256 +points: the two branches and a third commit, called the _merge base_, which is

257 +usually the common ancestor of the commits. The result of the merge is the sum

258 +of the changes between the merge base and each head. When you merge two

259 +branches with a regular merge commit, this results in a new commit which will

260 +end up as a merge base when they're merged again, because there is now a new

261 +common ancestor. Git doesn't have to consider changes that occurred before the

262 +merge base, so you don't have to re-resolve any conflicts you resolved before.

263 ++

264 +When you perform a squash merge, a merge commit isn't created; instead, the

265 +changes from one side are applied as a regular commit to the other side. This

266 +means that the merge base for these branches won't have changed, and so when Git

267 +goes to perform its next merge, it considers all of the changes that it

268 +considered the last time plus the new changes. That means any conflicts may

269 +need to be re-resolved. Similarly, anything using the `...` notation in `git

270 +diff`, `git log`, or a GUI will result in showing all of the changes since the

271 +original merge base.

272 ++

273 +As a consequence, if you want to merge two long-lived branches repeatedly, it's

274 +best to always use a regular merge commit.

275 +

276 Hooks

277 -----

278