threads / patch / 23448

patchmake description of "core.autocrlf" less ambiguous

Subject: [PATCH] make description of "core.autocrlf" less ambiguous

## tl;dr

3 messages between Apr 13, 2010 and Apr 14, 2010. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Will Palmer· Apr 13, 2010, 23:23 UTC · lore

The description for core.autocrlf refers to reads from / writes to the "filesystem". While the term is used elsewhere in the config documentation to refer to the filesystem git is hosted on, it is not only less clear from context in the case of core.autocrlf, but can also be plain inaccurate in many cases.

To make more clear the direction of removal / addition of CR when core.crlf is set, as well as to account for the usage of low-level commands such as hash-object or cat-file, we change "reading from the filesystem" to refer instead to "writing to the object database", and "writing to the filesystem" to "output or writing to the work tree"

Signed-off-by: Will Palmer <wmpalmer@gmail.com>
---

While I did some simple checks to ensure that my basic assumptions about how the commands I use daily seem to interact with core.autocrlf, I'll easily admit that I don't actually know all the places autocrlf is referenced, so I could be completely wrong about what generalizations can actually be made in the documentation. I'm fine with this patch being included, but it's pretty much just me "being bold" in order to say that I think the way it's currently phrased is wrong and confusing.

 Documentation/config.txt |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)

Show changes to Documentation/config.txt +5 −5

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 626b19a..125e9d5 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -198,11 +198,11 @@ core.quotepath::
 
 core.autocrlf::
 	If true, makes git convert `CRLF` at the end of lines in text files to
-	`LF` when reading from the filesystem, and convert in reverse when
-	writing to the filesystem.  The variable can be set to
-	'input', in which case the conversion happens only while
-	reading from the filesystem but files are written out with
-	`LF` at the end of lines.  A file is considered
+	`LF` when writing into the object database, and convert in reverse when
+	outputting those files or writing them to the work tree.  The variable
+	can be set to 'input', in which case the conversion happens only while
+	writing into the object database, but files are output and written to the
+	work tree with `LF` at the end of lines.  A file is considered
 	"text" (i.e. be subjected to the autocrlf mechanism) based on
 	the file's `crlf` attribute, or if `crlf` is unspecified,
 	based on the file's contents.  See linkgit:gitattributes[5].

-- 
1.7.1.rc1.248.gcefbb

Junio C Hamano· Apr 14, 2010, 13:55 UTC · re: Will Palmer · lore

Re: [PATCH] make description of "core.autocrlf" less ambiguous

Will Palmer <wmpalmer@gmail.com> writes:

Show 5 quoted lines

> While I did some simple checks to ensure that my basic assumptions about
> how the commands I use daily seem to interact with core.autocrlf, I'll
> easily admit that I don't actually know all the places autocrlf is
> referenced, so I could be completely wrong about what generalizations
> can actually be made in the documentation.

Thanks.

The description uses "reading from the filesystem" vs "writing to the filesystem" but as you may have noticed, there are cases that we do not interact with "the filesystem". Reading (e.g. "hash-object --stdin") from the standard input may read (e.g. "hash-object --stdin <file") from the filesystem, but we we may be reading from a "cmd | hash-object --stdin" pipe. Similarly, when we write to the standard output, "git to outside world" direction does not necessarily write to the filesystem. If you really want to be anal, these should probably be reworded to "converting the data from the outside world to the internal canonical representation" vs "converting the data git has for consumption by the outside world".

The "anal" description, however, is way too verbose, while it might be technically more correct. I think the current description would be a reasonable compromise, as "the filesystem" is the most typical case of "the outside world"; other than the "the standard input may come from the pipe" exception, I do not think there is much practical difference (but if there are more, we might need to sacrifice the readability and go with the "anal" one).

Very low level plumbing commands deliberately omit the conversion in order to show the raw data (e.g. cat-file), so it is not correct to reword it to "when output" as in your version.

Will Palmer· Apr 14, 2010, 14:49 UTC · re: Junio C Hamano · lore

Re: [PATCH] make description of "core.autocrlf" less ambiguous

On Wed, Apr 14, 2010 at 2:55 PM, Junio C Hamano <gitster@pobox.com> wrote:

> Very low level plumbing commands deliberately omit the conversion in order
> to show the raw data (e.g. cat-file), so it is not correct to reword it to
> "when output" as in your version.

Blame poor testing on my part, then. Yesterday, my tests showed "cat-file blob HEAD:a-crlf-file" outputting crlf lines, but today (with a script, rather than my typing commands in by-hand) that seems not to be the case.

I agree that verbose-and-anal is not the right way to go, but I still think the phrases reading from / writing to "the filesystem" sound very ambiguous, especially when related to a command which effects the way git stores things in its internal filesystem.

Most other uses of the term "filesystem" in the manpage use wording
such as: "...filesystems like NFS..",
 "..filesystems like FAT..", "traditional UNIX filesystems", etc. The
only non-explicit uses of the term talk about
"slow filesystems", which are clearly talking about something other
than git. The autocrlf mention is the only use of the
term "the filesystem".

Though at the time I thought I wasn't being anal enough, perhaps the correct move would be to go the opposite direction: technically not the-real-truth, but "good enough": maybe both references to "the filesystem" should just be replaced with "the work tree", which is the term used in the safecrlf section anyway?