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

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

[Will Palmer]

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(-)

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

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

[Junio C Hamano]

Will Palmer <wmpalmer@gmail.com> writes:

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

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

[Will Palmer]

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?