From: "brian m. carlson" <sandals@crustytoothpaste.net>
To: <git@vger.kernel.org>
Cc: "Martin Ågren" <martin.agren@gmail.com>
Subject: [PATCH v2 0/3] FAQ entries for merges and modified files
Date: Sun, 20 Sep 2020 23:22:28 +0000 [thread overview]
Message-ID: <20200920232231.1300394-1-sandals@crustytoothpaste.net> (raw)
In-Reply-To: <20200912204824.2824106-1-sandals@crustytoothpaste.net>
This series introduces a few new FAQ entries on various topics.
Changes from v1:
* Fix typos in commit messages.
* Talk about case-insensitive file names, not files, to avoid ambiguity.
* Warn people about rebases.
* Switch from "long-running" to "long-lived" and explain the situation
more clearly without relying on people understanding the meaning of
the adjective.
brian m. carlson (3):
docs: explain why squash merges are broken with long-running branches
docs: explain why reverts are not always applied on merge
docs: explain how to deal with files that are always modified
Documentation/gitfaq.txt | 86 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 86 insertions(+)
Diff-intervalle contre v1 :
1: c4f3e6e19c ! 1: 9f8f348fa8 docs: explain why squash merges are broken with long-running branches
@@ Commit message
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 mistakes, so let's add a FAQ entry
+ 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.
@@ Documentation/gitfaq.txt: How do I know if I want to do a fetch or a pull?::
+--------------------
+
+[[long-running-squash-merge]]
-+What kinds of problems can occur when merging long-running branches with squash merges?::
++What kinds of problems can occur when merging long-lived branches with squash merges?::
+ In general, there are a variety of problems that can occur when using squash
-+ merges with long-running branches. These can include seeing extra commits in
-+ `git log` output, with a GUI, or when using the `...` notation to express a
-+ range, as well as the possibility of needing to re-resolve conflicts again and
-+ again.
++ merges to merge two branches multiple times. These can include seeing extra
++ commits in `git log` output, with a GUI, or when using the `...` notation to
++ express a range, as well as the possibility of needing to re-resolve conflicts
++ again and again.
++
+When Git does a normal merge between two branches, it considers exactly three
+points: the two branches and a third commit, called the _merge base_, which is
+usually the common ancestor of the commits. The result of the merge is the sum
+of the changes between the merge base and each head. When you merge two
-+long-running branches with a regular merge commit, this results in a new commit
-+which will end up as a merge base when they're merged again, because there is
-+now a new common ancestor. Git doesn't have to consider changes that occurred
-+before the merge base, so you don't have to re-resolve any conflicts you
-+resolved before.
++branches with a regular merge commit, this results in a new commit which will
++end up as a merge base when they're merged again, because there is now a new
++common ancestor. Git doesn't have to consider changes that occurred before the
++merge base, so you don't have to re-resolve any conflicts you resolved before.
++
+When you perform a squash merge, a merge commit isn't created; instead, the
+changes from one side are applied as a regular commit to the other side. This
@@ Documentation/gitfaq.txt: How do I know if I want to do a fetch or a pull?::
+diff`, `git log`, or a GUI will result in showing all of the changes since the
+original merge base.
++
-+As a consequence, if you want to merge two long-running branches, it's best to
-+always use a regular merge commit.
++As a consequence, if you want to merge two long-lived branches repeatedly, it's
++best to always use a regular merge commit.
+
Hooks
-----
2: 645798d18b ! 2: 248d7e7b4b docs: explain why reverts are not always applied on merge
@@ Commit message
A common scenario is for a user to apply a change to one branch and
cherry-pick it into another, then later revert it in the first branch.
This results in the change being present when the two branches are
- merge, which is confusing to many users.
+ merged, which is confusing to many users.
We already have documentation for how this works in `git merge`, but it
is clear from the frequency with which this is asked that it's hard to
@@ Commit message
## Documentation/gitfaq.txt ##
@@ Documentation/gitfaq.txt: original merge base.
- As a consequence, if you want to merge two long-running branches, it's best to
- always use a regular merge commit.
+ As a consequence, if you want to merge two long-lived branches repeatedly, it's
+ best to always use a regular merge commit.
+[[merge-two-revert-one]]
+If I make a change on two branches but revert it on one, why does the merge of those branches include the change?::
@@ Documentation/gitfaq.txt: original merge base.
+If this is a problem for you, you can do a rebase instead, rebasing the branch
+with the revert onto the other branch. A rebase in this scenario will revert
+the change, because a rebase applies each individual commit, including the
-+revert.
++revert. Note that rebases rewrite history, so you should avoid rebasing
++published branches unless you're sure you're comfortable with that. See the
++NOTES section in linkgit:git-rebase[1] for more details.
+
Hooks
-----
3: 10ad244b1e ! 3: e2495d4358 docs: explain how to deal with files that are always modified
@@ Metadata
## Commit message ##
docs: explain how to deal with files that are always modified
- Users frequently have problems where two files differ only in case,
+ Users frequently have problems where two filenames differ only in case,
causing one of those files to show up consistently as being modified.
Let's add a FAQ entry that explains how to deal with that.
@@ Documentation/gitfaq.txt: information about how to configure files as text or bi
+ Internally, Git always stores file names as sequences of bytes and doesn't
+ perform any encoding or case folding. However, Windows and macOS by default
+ both perform case folding on file names. As a result, it's possible to end up
-+ with multiple files or directories that differ in case. Git can handle this
-+ just fine, but the file system can store only one of these files, so when Git
-+ reads the other file to see its contents, it looks modified.
++ with multiple files or directories whose names differ only in case. Git can
++ handle this just fine, but the file system can store only one of these files,
++ so when Git reads the other file to see its contents, it looks modified.
++
+It's best to remove one of the files such that you only have one file. You can
+do this with commands like the following (assuming two files `AFile.txt` and
next prev parent reply other threads:[~2020-09-20 23:23 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-12 20:48 [PATCH 0/3] FAQ entries for merges and modified files brian m. carlson
2020-09-12 20:48 ` [PATCH 1/3] docs: explain why squash merges are broken with long-running branches brian m. carlson
2020-09-13 15:05 ` Martin Ågren
2020-09-13 17:12 ` brian m. carlson
2020-09-12 20:48 ` [PATCH 2/3] docs: explain why reverts are not always applied on merge brian m. carlson
2020-09-13 15:12 ` Martin Ågren
2020-09-12 20:48 ` [PATCH 3/3] docs: explain how to deal with files that are always modified brian m. carlson
2020-09-13 15:13 ` Martin Ågren
2020-09-12 21:48 ` [PATCH 0/3] FAQ entries for merges and modified files Junio C Hamano
2020-09-20 23:22 ` brian m. carlson [this message]
2020-09-20 23:22 ` [PATCH v2 1/3] docs: explain why squash merges are broken with long-running branches brian m. carlson
2020-09-20 23:22 ` [PATCH v2 2/3] docs: explain why reverts are not always applied on merge brian m. carlson
2020-09-20 23:22 ` [PATCH v2 3/3] docs: explain how to deal with files that are always modified brian m. carlson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200920232231.1300394-1-sandals@crustytoothpaste.net \
--to=sandals@crustytoothpaste.net \
--cc=git@vger.kernel.org \
--cc=martin.agren@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).