git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / Atom feed
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
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

  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 " 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

  List information: http://vger.kernel.org/majordomo-info.html

* 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

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for the project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git