[PATCH v3 0/4] Documentation for common user misconceptions

[PATCH v3 0/4] Documentation for common user misconceptions

[brian m. carlson]

This series includes four patches that update the documentation to
address common user misconceptions.

Changes from v2:
* Move author and committer information to git-commit(1) where people
  will look for it.
* Move guidance on user.name format to git-commit(1) as well and mention
  a shortened form of the advice in the `user.name` description.
* Use a parenthetical to describe a "personal name" without contrasting
  it with a username.
* Offer a potential solution for people who want to ignore tracked
  files by recommending a templating mechanism.
* Be slightly more verbose about why memory is wasted with
  http.postBuffer.

Changes from v1:
* Remove parenthetical which was confusing.
* Add two more patches.

brian m. carlson (4):
  doc: move author and committer information to git-commit(1)
  doc: provide guidance on user.name format
  doc: dissuade users from trying to ignore tracked files
  docs: mention when increasing http.postBuffer is valuable

 Documentation/config/http.txt      |  8 ++++++
 Documentation/config/user.txt      |  7 +++++-
 Documentation/git-commit-tree.txt  | 39 ++++-------------------------
 Documentation/git-commit.txt       | 40 +++++++++++++++++++++++++++---
 Documentation/git-update-index.txt | 16 ++++++++++++
 5 files changed, 72 insertions(+), 38 deletions(-)

Range-diff against v2:
1:  603a9f8f9a < -:  ---------- doc: provide guidance on user.name format
-:  ---------- > 1:  b39b365f54 doc: move author and committer information to git-commit(1)
-:  ---------- > 2:  b7d805427c doc: provide guidance on user.name format
2:  0da41623a5 ! 3:  7644af0b07 doc: dissuade users from trying to ignore tracked files
    @@ Commit message
         pitfalls in the documentation for git update-index so that users know
         they should explore alternate solutions.
     
    +    In additon, let's provide a recommended solution to dealing with the
    +    common case of configuration files, since there are well-known
    +    approaches used successfully in many environments.
    +
         Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
     
      ## Documentation/git-update-index.txt ##
    @@ Documentation/git-update-index.txt: The untracked cache extension can be enabled
     +the index when performing certain operations.  In general, Git does not
     +provide a way to ignore changes to tracked files, so alternate solutions
     +are recommended.
    ++
    ++If the file you want to change is some sort of configuration file (say,
    ++for a build tool, IDE, or editor), a common solution is to use a
    ++templating mechanism, such as Ruby's ERB, to generate the ignored
    ++configuration file from a template stored in the repository and a source
    ++of data using a script or build step.
     +
      SEE ALSO
      --------
3:  89fe11b951 ! 4:  d096763e7a docs: mention when increasing http.postBuffer is valuable
    @@ Documentation/config/http.txt: http.postBuffer::
     +server or a proxy only supports HTTP/1.0 or is noncompliant with the
     +HTTP standard.  Raising this is not, in general, an effective solution
     +for most push problems, but can increase memory consumption
    -+significantly.
    ++significantly since the entire buffer is allocated for even small
    ++pushes.
      
      http.lowSpeedLimit, http.lowSpeedTime::
      	If the HTTP transfer speed is less than 'http.lowSpeedLimit'

[PATCH v3 1/4] doc: move author and committer information to git-commit(1)

[brian m. carlson]

While at one time it made perfect sense to store information about
configuring author and committer information in the documentation for
git commit-tree, in modern Git that operation is seldom used.  Most
users will use git commit and expect to find comprehensive documentation
about its use in the manual page for that command.

Considering that there is significant confusion about how one is to use
the user.name and user.email variables, let's put as much documentation
as possible into an obvious place where users will be more likely to
find it.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/config/user.txt     |  2 +-
 Documentation/git-commit-tree.txt | 39 ++++---------------------------
 Documentation/git-commit.txt      | 34 ++++++++++++++++++++++++---
 3 files changed, 37 insertions(+), 38 deletions(-)

diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
index 0557cbbceb..a1f80e823c 100644
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.txt
@@ -13,7 +13,7 @@ committer.email::
 	Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
 	`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
 	`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
-	See linkgit:git-commit-tree[1] for more information.
+	See linkgit:git-commit[1] for more information.
 
 user.useConfigOnly::
 	Instruct Git to avoid trying to guess defaults for `user.email`
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 4b90b9c12a..d518dffce0 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -42,6 +42,10 @@ tend to just write the result to the file that is pointed at by
 `.git/HEAD`, so that we can always see what the last committed
 state was.
 
+A commit comment is read from stdin. If a changelog
+entry is not provided via "<" redirection, 'git commit-tree' will just wait
+for one to be entered and terminated with ^D.
+
 OPTIONS
 -------
 <tree>::
@@ -69,40 +73,6 @@ OPTIONS
 	Do not GPG-sign commit, to countermand a `--gpg-sign` option
 	given earlier on the command line.
 
-
-Commit Information
-------------------
-
-A commit encapsulates:
-
-- all parent object ids
-- author name, email and date
-- committer name and email and the commit time.
-
-While parent object ids are provided on the command line, author and
-committer information is taken from the following environment variables,
-if set:
-
-	GIT_AUTHOR_NAME
-	GIT_AUTHOR_EMAIL
-	GIT_AUTHOR_DATE
-	GIT_COMMITTER_NAME
-	GIT_COMMITTER_EMAIL
-	GIT_COMMITTER_DATE
-
-(nb "<", ">" and "\n"s are stripped)
-
-In case (some of) these environment variables are not set, the information
-is taken from the configuration items user.name and user.email, or, if not
-present, the environment variable EMAIL, or, if that is not set,
-system user name and the hostname used for outgoing mail (taken
-from `/etc/mailname` and falling back to the fully qualified hostname when
-that file does not exist).
-
-A commit comment is read from stdin. If a changelog
-entry is not provided via "<" redirection, 'git commit-tree' will just wait
-for one to be entered and terminated with ^D.
-
 include::date-formats.txt[]
 
 Discussion
@@ -117,6 +87,7 @@ FILES
 SEE ALSO
 --------
 linkgit:git-write-tree[1]
+linkgit:git-commit[1]
 
 GIT
 ---
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index afa7b75a23..f684f7fdc2 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -352,9 +352,6 @@ changes to tracked files.
 	these files are also staged for the next commit on top
 	of what have been staged before.
 
-:git-commit: 1
-include::date-formats.txt[]
-
 EXAMPLES
 --------
 When recording your own work, the contents of modified files in
@@ -448,6 +445,37 @@ alter the order the changes are committed, because the merge
 should be recorded as a single commit.  In fact, the command
 refuses to run when given pathnames (but see `-i` option).
 
+COMMIT INFORMATION
+------------------
+
+A commit encapsulates:
+
+- all parent object ids
+- author name, email and date
+- committer name and email and the commit time.
+
+While parent object ids are provided on the command line, author and
+committer information is taken from the following environment variables,
+if set:
+
+	GIT_AUTHOR_NAME
+	GIT_AUTHOR_EMAIL
+	GIT_AUTHOR_DATE
+	GIT_COMMITTER_NAME
+	GIT_COMMITTER_EMAIL
+	GIT_COMMITTER_DATE
+
+(nb "<", ">" and "\n"s are stripped)
+
+In case (some of) these environment variables are not set, the information
+is taken from the configuration items user.name and user.email, or, if not
+present, the environment variable EMAIL, or, if that is not set,
+system user name and the hostname used for outgoing mail (taken
+from `/etc/mailname` and falling back to the fully qualified hostname when
+that file does not exist).
+
+:git-commit: 1
+include::date-formats.txt[]
 
 DISCUSSION
 ----------

[PATCH v3 2/4] doc: provide guidance on user.name format

[brian m. carlson]

It's a frequent misconception that the user.name variable controls
authentication in some way, and as a result, beginning users frequently
attempt to change it when they're having authentication troubles.
Document that the convention is that this variable represents some form
of a human's personal name, although that is not required.  In addition,
address concerns about whether Unicode is supported.

Use the term "personal name" as this is likely to draw the intended
contrast, be applicable across cultures which may have different naming
conventions, and be easily understandable to people who do not speak
English as their first language.  Indicate that "some form" is
conventionally used, as people may use a nickname or preferred name
instead of a full legal name.

Point users who may be confused about authentication to an appropriate
configuration option instead.  Provide a shortened form of this
information in the configuration option description.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/config/user.txt | 7 ++++++-
 Documentation/git-commit.txt  | 6 ++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
index a1f80e823c..f0edb06329 100644
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.txt
@@ -13,7 +13,12 @@ committer.email::
 	Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
 	`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
 	`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
-	See linkgit:git-commit[1] for more information.
++
+Note that the `name` forms of these variables conventionally refer to
+some form of a personal name.
+See linkgit:git-commit[1] for more information on these settings and
+the `credential.username` option if you're looking for authentication
+credentials instead.
 
 user.useConfigOnly::
 	Instruct Git to avoid trying to guess defaults for `user.email`
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index f684f7fdc2..3a69d82d52 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -467,6 +467,12 @@ if set:
 
 (nb "<", ">" and "\n"s are stripped)
 
+The author and committer names are by convention some form of a personal name
+(that is, the name by which other humans refer to you), although Git does not
+enforce or require any particular form. Arbitrary Unicode may be used, subject
+to the constraints listed above. This name has no effect on authentication; for
+that, see the `credential.username` variable in linkgit::git-config[1].
+
 In case (some of) these environment variables are not set, the information
 is taken from the configuration items user.name and user.email, or, if not
 present, the environment variable EMAIL, or, if that is not set,

[PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[brian m. carlson]

It is quite common for users to want to ignore the changes to a file
that Git tracks.  Common scenarios for this case are IDE settings and
configuration files, which should generally not be tracked and possibly
generated from tracked files using a templating mechanism.

However, users learn about the assume-unchanged and skip-worktree bits
and try to use them to do this anyway.  This is problematic, because
when these bits are set, many operations behave as the user expects, but
they usually do not help when git checkout needs to replace a file.

There is no sensible behavior in this case, because sometimes the data
is precious, such as certain configuration files, and sometimes it is
irrelevant data that the user would be happy to discard.

Since this is not a supported configuration and users are prone to
misuse the existing features for unintended purposes, causing general
sadness and confusion, let's document the existing behavior and the
pitfalls in the documentation for git update-index so that users know
they should explore alternate solutions.

In additon, let's provide a recommended solution to dealing with the
common case of configuration files, since there are well-known
approaches used successfully in many environments.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-update-index.txt | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 1c4d146a41..11230376c8 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -543,6 +543,22 @@ The untracked cache extension can be enabled by the
 `core.untrackedCache` configuration variable (see
 linkgit:git-config[1]).
 
+NOTES
+-----
+
+Users often try to use the ``assume unchanged'' and skip-worktree bits
+to tell Git to ignore changes to files that are tracked.  This does not
+work as expected, since Git may still check working tree files against
+the index when performing certain operations.  In general, Git does not
+provide a way to ignore changes to tracked files, so alternate solutions
+are recommended.
+
+If the file you want to change is some sort of configuration file (say,
+for a build tool, IDE, or editor), a common solution is to use a
+templating mechanism, such as Ruby's ERB, to generate the ignored
+configuration file from a template stored in the repository and a source
+of data using a script or build step.
+
 SEE ALSO
 --------
 linkgit:git-config[1],

[PATCH v3 4/4] docs: mention when increasing http.postBuffer is valuable

[brian m. carlson]

Users in a wide variety of situations find themselves with HTTP push
problems.  Oftentimes these issues are due to antivirus software,
filtering proxies, or other man-in-the-middle situations; other times,
they are due to simple unreliability of the network.

However, a common solution to HTTP push problems found online is to
increase http.postBuffer.  This works for none of the aforementioned
situations and is only useful in a small, highly restricted number of
cases: essentially, when the connection does not properly support
HTTP/1.1.

Document when raising this value is appropriate and what it actually
does, and discourage people from using it as a general solution for push
problems, since it is not effective there.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/config/http.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
index 5a32f5b0a5..08b375fe95 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -199,6 +199,14 @@ http.postBuffer::
 	Transfer-Encoding: chunked is used to avoid creating a
 	massive pack file locally.  Default is 1 MiB, which is
 	sufficient for most requests.
++
+Note that raising this limit is only effective for disabling chunked
+transfer encoding and therefore should be used only where the remote
+server or a proxy only supports HTTP/1.0 or is noncompliant with the
+HTTP standard.  Raising this is not, in general, an effective solution
+for most push problems, but can increase memory consumption
+significantly since the entire buffer is allocated for even small
+pushes.
 
 http.lowSpeedLimit, http.lowSpeedTime::
 	If the HTTP transfer speed is less than 'http.lowSpeedLimit'

RE: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[rsbecker]

On November 2, 2019 3:26 PM, brian m. carlson wrote:
> It is quite common for users to want to ignore the changes to a file that
Git
> tracks.  Common scenarios for this case are IDE settings and configuration
> files, which should generally not be tracked and possibly generated from
> tracked files using a templating mechanism.
> 
> However, users learn about the assume-unchanged and skip-worktree bits
> and try to use them to do this anyway.  This is problematic, because when
> these bits are set, many operations behave as the user expects, but they
> usually do not help when git checkout needs to replace a file.
> 
> There is no sensible behavior in this case, because sometimes the data is
> precious, such as certain configuration files, and sometimes it is
irrelevant
> data that the user would be happy to discard.
> 
> Since this is not a supported configuration and users are prone to misuse
the
> existing features for unintended purposes, causing general sadness and
> confusion, let's document the existing behavior and the pitfalls in the
> documentation for git update-index so that users know they should explore
> alternate solutions.
> 
> In additon, let's provide a recommended solution to dealing with the
> common case of configuration files, since there are well-known approaches
> used successfully in many environments.

Just noodling about a potential solution. If we assume the use case that
files are modified by an IDE that have no real relevance, but should not
interfere with other git operations including checkout...

What if we introduce something like .gitignore.changes, with the same syntax
as .gitignore. The difference is files listed in this file will not show in
git status (or could show as "changes ignored" with an option to enable
that. The only way to have the changes considered would be git add -f, so
git add . and git commit -a would not pick up the changes. From checkout's
perspective, the file would be considered unmodified so if a change is
incoming for that path, checkout replaces it instead of rejecting the
checkout, otherwise the file is untouched. Pull would act similarly. Branch
switching would be permitted without stashing the files - they would remain
unchanged unless the switch modified the files.

OTOH, this is a change that is most relevant to IDE users, so JGit would
have to implement it as well to really get any real benefit.

This does have some benefit in post-install situations as well as the IDE
use-case, but for that I might want to consider finer granularity, like some
way to identify regions of files being ignored. This being a pretty deep
rabbit hole we'd end up following.

If this idea seems reasonable, it might make a nice small project for
someone, possibly me, if I could unentangle from my current hellish $DAYJOB
project.

Just my few coins of thought.

Randall

Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)

[Jakub Narebski]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> While at one time it made perfect sense to store information about
> configuring author and committer information in the documentation for
> git commit-tree, in modern Git that operation is seldom used.  Most
> users will use git commit and expect to find comprehensive documentation
> about its use in the manual page for that command.
>
> Considering that there is significant confusion about how one is to use
> the user.name and user.email variables, let's put as much documentation
> as possible into an obvious place where users will be more likely to
> find it.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/config/user.txt     |  2 +-
>  Documentation/git-commit-tree.txt | 39 ++++---------------------------
>  Documentation/git-commit.txt      | 34 ++++++++++++++++++++++++---
>  3 files changed, 37 insertions(+), 38 deletions(-)
>
> diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
> index 0557cbbceb..a1f80e823c 100644
> --- a/Documentation/config/user.txt
> +++ b/Documentation/config/user.txt
> @@ -13,7 +13,7 @@ committer.email::
>  	Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
>  	`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
>  	`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
> -	See linkgit:git-commit-tree[1] for more information.
> +	See linkgit:git-commit[1] for more information.

O.K., lets refer users to the command they actually use.

>  user.useConfigOnly::
>  	Instruct Git to avoid trying to guess defaults for `user.email`
> diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
> index 4b90b9c12a..d518dffce0 100644
> --- a/Documentation/git-commit-tree.txt
> +++ b/Documentation/git-commit-tree.txt
> @@ -42,6 +42,10 @@ tend to just write the result to the file that is pointed at by
>  `.git/HEAD`, so that we can always see what the last committed
>  state was.
>  
> +A commit comment is read from stdin. If a changelog
> +entry is not provided via "<" redirection, 'git commit-tree' will just wait
> +for one to be entered and terminated with ^D.
> +

I understand this is what is extracted from the removed part (moved to
git-commit documentation).  But I think it is not enough to understand
how to actually use this command; this change makes reference
documentation not self contained.

>  OPTIONS
>  -------
>  <tree>::
> @@ -69,40 +73,6 @@ OPTIONS
>  	Do not GPG-sign commit, to countermand a `--gpg-sign` option
>  	given earlier on the command line.
>  
> -
> -Commit Information
> -------------------
> -
> -A commit encapsulates:
> -
> -- all parent object ids
> -- author name, email and date
> -- committer name and email and the commit time.

O.K., I can understand moving this information to a better place
(nb. what about gitglossry?).

> -
> -While parent object ids are provided on the command line, author and
> -committer information is taken from the following environment variables,
> -if set:
> -
> -	GIT_AUTHOR_NAME
> -	GIT_AUTHOR_EMAIL
> -	GIT_AUTHOR_DATE
> -	GIT_COMMITTER_NAME
> -	GIT_COMMITTER_EMAIL
> -	GIT_COMMITTER_DATE
> -
> -(nb "<", ">" and "\n"s are stripped)
> -
> -In case (some of) these environment variables are not set, the information
> -is taken from the configuration items user.name and user.email, or, if not
> -present, the environment variable EMAIL, or, if that is not set,
> -system user name and the hostname used for outgoing mail (taken
> -from `/etc/mailname` and falling back to the fully qualified hostname when
> -that file does not exist).

I'm not sure if this should not be left here, perhaps extracted into
separate fragment file to be included in both git-commit-tree.txt and in
git-commit.txt

I see that we are missing the ebvious information that if GIT_*_DATE
environment variables are not set, Git will use current date and time.
Is there a place where we say what format GIT_*_DATE needs to be in?

> -
> -A commit comment is read from stdin. If a changelog
> -entry is not provided via "<" redirection, 'git commit-tree' will just wait
> -for one to be entered and terminated with ^D.
> -
>  include::date-formats.txt[]
>  
>  Discussion
> @@ -117,6 +87,7 @@ FILES
>  SEE ALSO
>  --------
>  linkgit:git-write-tree[1]
> +linkgit:git-commit[1]

All right.

>  
>  GIT
>  ---
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index afa7b75a23..f684f7fdc2 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -352,9 +352,6 @@ changes to tracked files.
>  	these files are also staged for the next commit on top
>  	of what have been staged before.
>  
> -:git-commit: 1
> -include::date-formats.txt[]
> -

All right, it is moved down, not removed.

>  EXAMPLES
>  --------
>  When recording your own work, the contents of modified files in
> @@ -448,6 +445,37 @@ alter the order the changes are committed, because the merge
>  should be recorded as a single commit.  In fact, the command
>  refuses to run when given pathnames (but see `-i` option).
>  
> +COMMIT INFORMATION
> +------------------
> +
> +A commit encapsulates:
> +
> +- all parent object ids
> +- author name, email and date
> +- committer name and email and the commit time.
> +
> +While parent object ids are provided on the command line,
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This was true for `git commit-tree`, with the following synopsis

  git commit-tree <tree> [(-p <parent>)…​]
  git commit-tree [(-p <parent>)…​] [-S[<keyid>]] [(-m <message>)…​]
  		  [(-F <file>)…​] <tree>

This is decidely *NOT true* for `git commit`:

  git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
  	   [--dry-run] [(-c | -C | --fixup | --squash) <commit>]
  	   [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
  	   [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
  	   [--date=<date>] [--cleanup=<mode>] [--[no-]status]
  	   [-i | -o] [-S[<keyid>]] [--] [<file>…​]

Parent ids are *not* provided on the command line.

>                                                            author and
> +committer information is taken from the following environment variables,
> +if set:
> +
> +	GIT_AUTHOR_NAME
> +	GIT_AUTHOR_EMAIL
> +	GIT_AUTHOR_DATE
> +	GIT_COMMITTER_NAME
> +	GIT_COMMITTER_EMAIL
> +	GIT_COMMITTER_DATE
> +
> +(nb "<", ">" and "\n"s are stripped)
> +
> +In case (some of) these environment variables are not set, the information
> +is taken from the configuration items user.name and user.email, or, if not
> +present, the environment variable EMAIL, or, if that is not set,
> +system user name and the hostname used for outgoing mail (taken
> +from `/etc/mailname` and falling back to the fully qualified hostname when
> +that file does not exist).

I think that this description, while perfectly fine for plumbing command
`git commit-tree`, might be needlesly confusing for `git commit` users,
as it describes less often common used way of providing committer and
author information first.

Also in `git commit` there are *options* specifically for adjusting how
committer and author information is handled: `--reuse-message=<commit>`
and `--reedit-message=<commit>`, `--reset-author` (doesn't make sense
alone), `--author=<author>` and `--date=<date>`.

Maybe describe usual way first, then describe the various options and
their priority?

> +
> +:git-commit: 1
> +include::date-formats.txt[]
>  
>  DISCUSSION
>  ----------

Best,
-- 
Jakub Narębski

Re: [PATCH v3 2/4] doc: provide guidance on user.name format

[Jakub Narebski]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> It's a frequent misconception that the user.name variable controls
> authentication in some way, and as a result, beginning users frequently
> attempt to change it when they're having authentication troubles.
> Document that the convention is that this variable represents some form
> of a human's personal name, although that is not required.  In addition,
> address concerns about whether Unicode is supported.
>
> Use the term "personal name" as this is likely to draw the intended
> contrast, be applicable across cultures which may have different naming
> conventions, and be easily understandable to people who do not speak
> English as their first language.  Indicate that "some form" is
> conventionally used, as people may use a nickname or preferred name
> instead of a full legal name.

This reminds me of "Personal names around the world" by W3C
https://www.w3.org/International/questions/qa-personal-names

>
> Point users who may be confused about authentication to an appropriate
> configuration option instead.  Provide a shortened form of this
> information in the configuration option description.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>

I like this change!  Un-confusing users is always a win.

> ---
>  Documentation/config/user.txt | 7 ++++++-
>  Documentation/git-commit.txt  | 6 ++++++
>  2 files changed, 12 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt
> index a1f80e823c..f0edb06329 100644
> --- a/Documentation/config/user.txt
> +++ b/Documentation/config/user.txt
> @@ -13,7 +13,12 @@ committer.email::
>  	Also, all of these can be overridden by the `GIT_AUTHOR_NAME`,
>  	`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,
>  	`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.
> -	See linkgit:git-commit[1] for more information.
> ++
> +Note that the `name` forms of these variables conventionally refer to
> +some form of a personal name.
> +See linkgit:git-commit[1] for more information on these settings and
> +the `credential.username` option if you're looking for authentication
> +credentials instead.

Minor nit: should this be one paragraph or two - the linebreak after "of
a personal name." looks a bit strange?

No need for a change: just idly wondering.

>  
>  user.useConfigOnly::
>  	Instruct Git to avoid trying to guess defaults for `user.email`
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index f684f7fdc2..3a69d82d52 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -467,6 +467,12 @@ if set:
>  
>  (nb "<", ">" and "\n"s are stripped)
>  
> +The author and committer names are by convention some form of a personal name
> +(that is, the name by which other humans refer to you), although Git does not
> +enforce or require any particular form. Arbitrary Unicode may be used, subject
> +to the constraints listed above. This name has no effect on authentication; for
> +that, see the `credential.username` variable in linkgit::git-config[1].

Just ensuring that I understand it correctly: by "constraints" you mean
stripping of "<", ">" and "\n" (and by implication "\0")?

Should we say anything about encoding?

> +
>  In case (some of) these environment variables are not set, the information
>  is taken from the configuration items user.name and user.email, or, if not
>  present, the environment variable EMAIL, or, if that is not set,

Best,
-- 
Jakub Narębski

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[Jakub Narebski]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> It is quite common for users to want to ignore the changes to a file
> that Git tracks.  Common scenarios for this case are IDE settings and
> configuration files, which should generally not be tracked and possibly
> generated from tracked files using a templating mechanism.
>
> However, users learn about the assume-unchanged and skip-worktree bits
> and try to use them to do this anyway.  This is problematic, because
> when these bits are set, many operations behave as the user expects, but
> they usually do not help when git checkout needs to replace a file.
>
> There is no sensible behavior in this case, because sometimes the data
> is precious, such as certain configuration files, and sometimes it is
> irrelevant data that the user would be happy to discard.
>
> Since this is not a supported configuration and users are prone to
> misuse the existing features for unintended purposes, causing general
> sadness and confusion, let's document the existing behavior and the
> pitfalls in the documentation for git update-index so that users know
> they should explore alternate solutions.
>
> In additon, let's provide a recommended solution to dealing with the
> common case of configuration files, since there are well-known
> approaches used successfully in many environments.

All right, looks sensible and good thing to have.

> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/git-update-index.txt | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
>
> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
> index 1c4d146a41..11230376c8 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -543,6 +543,22 @@ The untracked cache extension can be enabled by the
>  `core.untrackedCache` configuration variable (see
>  linkgit:git-config[1]).
>  
> +NOTES
> +-----
> +
> +Users often try to use the ``assume unchanged'' and skip-worktree bits

Why the change between formatting '``assume unchanged''' (with double
quotes and space separated) and 'skip-worktree' (without quotes, and
kebab-cased)?  In the commit message you write about assume-unchanged
and skip-worktree.

I guess that follows the inconsistency in git-update-index(1) headers,
namely we have

  USING ``ASSUME UNCHANGED'' BIT
  ------------------------------

but

  SKIP-WORKTREE BIT
  -----------------

This incconsistency is much more viible when both names are on the same
line, however.

This is a minor nit.

> +to tell Git to ignore changes to files that are tracked.  This does not
> +work as expected, since Git may still check working tree files against
> +the index when performing certain operations.  In general, Git does not
> +provide a way to ignore changes to tracked files, so alternate solutions
> +are recommended.

I'm not sure if it is a place for it, but the proposed text treats
assume-unchanged and skip-worktree as similarly unsuited for intended
purpose.  However, their failure modes are different: (ab)using the
assume-unchanged for "ignore changed to tracked files" may lead to data
loss (as changes are overwritten), while with skip-worktree the trouble
is that some operations that should succeed (like unstashing) are
unnecessarily blocked - but no data loss.

> +
> +If the file you want to change is some sort of configuration file (say,
> +for a build tool, IDE, or editor), a common solution is to use a
> +templating mechanism, such as Ruby's ERB, to generate the ignored
> +configuration file from a template stored in the repository and a source
> +of data using a script or build step.

I would really like to see a simple example of such template, so that
even people who are unfamiliar with Ruby's ERB can think of equivalent
solution for their language or toolchain of choice.

> +
>  SEE ALSO
>  --------
>  linkgit:git-config[1],

Best,
-- 
Jakub Narębski

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[Jakub Narebski]

<rsbecker@nexbridge.com> writes:

> On November 2, 2019 3:26 PM, brian m. carlson wrote:
>> It is quite common for users to want to ignore the changes to a file that Git
>> tracks.  Common scenarios for this case are IDE settings and configuration
>> files, which should generally not be tracked and possibly generated from
>> tracked files using a templating mechanism.
>> 
>> However, users learn about the assume-unchanged and skip-worktree bits
>> and try to use them to do this anyway.  This is problematic, because when
>> these bits are set, many operations behave as the user expects, but they
>> usually do not help when git checkout needs to replace a file.
[...]
> Just noodling about a potential solution. If we assume the use case that
> files are modified by an IDE that have no real relevance, but should not
> interfere with other git operations including checkout...
>
> What if we introduce something like .gitignore.changes, with the same syntax
> as .gitignore. The difference is files listed in this file will not show in
> `git status` (or could show as "changes ignored" with an option to enable
> that. The only way to have the changes considered would be `git add -f`, so
> `git add .` and `git commit -a` would not pick up the changes.
[...]

I think it would be better and easier to add new attribute and use
.gitattributes instead of a new .gitignore.changes (and its
per-repository, per-user and system-wide version).

> If this idea seems reasonable, it might make a nice small project for
> someone, possibly me, if I could unentangle from my current hellish $DAYJOB
> project.

I wish you luck.

The fact that it was nod done yet may mean that there are some annoying
corner-cases in the concept, or that it is not commonly useful... or
maybe that is the problem that needs reframing.

Best,
-- 
Jakub Narębski

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 2696 bytes --]

On 2019-11-03 at 15:04:44, Jakub Narebski wrote:
> Why the change between formatting '``assume unchanged''' (with double
> quotes and space separated) and 'skip-worktree' (without quotes, and
> kebab-cased)?  In the commit message you write about assume-unchanged
> and skip-worktree.
> 
> I guess that follows the inconsistency in git-update-index(1) headers,
> namely we have
> 
>   USING ``ASSUME UNCHANGED'' BIT
>   ------------------------------
> 
> but
> 
>   SKIP-WORKTREE BIT
>   -----------------
> 
> This incconsistency is much more viible when both names are on the same
> line, however.

Yeah, I can change them to make them consistent.  I did preserve the
existing formatting for both, as you mentioned.

> I'm not sure if it is a place for it, but the proposed text treats
> assume-unchanged and skip-worktree as similarly unsuited for intended
> purpose.  However, their failure modes are different: (ab)using the
> assume-unchanged for "ignore changed to tracked files" may lead to data
> loss (as changes are overwritten), while with skip-worktree the trouble
> is that some operations that should succeed (like unstashing) are
> unnecessarily blocked - but no data loss.

I agree the failure modes can be different, but from my experience there
are people who have seen checkout failures with both bits set
independently.  I'm not exactly sure what those cases are, but folks do
see them on Stack Overflow quite frequently.

Even if there is a difference in failure modes, I'd rather encourage
people to just not use this mechanism rather than explain why or in
which cases it won't do what you want.

> I would really like to see a simple example of such template, so that
> even people who are unfamiliar with Ruby's ERB can think of equivalent
> solution for their language or toolchain of choice.

I hesitated to mention ERB, but I wasn't sure that folks would know what
we meant by a "templating mechanism".  The reason I had chosen to
mention it is that someone could search for "Ruby ERB" and find out what
it looked like and then look for an option in their own language.

My concern with adding such a template is that an example will likely
grow this section quite a bit, and it's meant as a short aside to help
people avoid making a common mistake and guide them to a proper solution
rather than a comprehensive howto.  I'm planning on adding a FAQ
document in the future that covers a lot of these issues in more detail
and helps folks figure out solutions to common problems, and I'd prefer
to explain this more in depth there.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]

Re: [PATCH v3 2/4] doc: provide guidance on user.name format

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1711 bytes --]

On 2019-11-03 at 13:13:57, Jakub Narebski wrote:
> This reminds me of "Personal names around the world" by W3C
> https://www.w3.org/International/questions/qa-personal-names

I hadn't read that document before, but it's definitely the approach I
was going for.  People all over the world use Git, and we should make it
as usable for all of those people as we can.

> Minor nit: should this be one paragraph or two - the linebreak after "of
> a personal name." looks a bit strange?
> 
> No need for a change: just idly wondering.

Good question.  I had explained this in my original patch but had to
reformat the patch and forgot to include this.

The existing text uses a line break after each sentence, and in AsciiDoc
that doesn't introduce a new paragraph; only a blank line does that.  I
opted to keep this consistent with the rest of the description of this
item.

> Just ensuring that I understand it correctly: by "constraints" you mean
> stripping of "<", ">" and "\n" (and by implication "\0")?

Yes, that's correct.

> Should we say anything about encoding?

I don't think it's necessary; since we told people that arbitrary
Unicode is permitted, hopefully they will determine that they should use
UTF-8, or, for Windows environment variables, UTF-16.  Unfortunately,
there's not a good way to get UTF-8 environment variables in Windows, so
"Unicode" is the best we can do there.

I'm happy to gloss over the fact that they can use something else
because (a) while they can, they should not and (b) if they do, they'll
know that they're obviously restricted to that subset of Unicode.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[Jakub Narebski]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:
> On 2019-11-03 at 15:04:44, Jakub Narebski wrote:

>> Why the change between formatting '``assume unchanged''' (with double
>> quotes and space separated) and 'skip-worktree' (without quotes, and
>> kebab-cased)?  In the commit message you write about assume-unchanged
>> and skip-worktree.
>> 
>> I guess that follows the inconsistency in git-update-index(1) headers,
>> namely we have
>> 
>>   USING ``ASSUME UNCHANGED'' BIT
>>   ------------------------------
>> 
>> but
>> 
>>   SKIP-WORKTREE BIT
>>   -----------------
>> 
>> This inconsistency is much more visible when both names are on the same
>> line, however.
>
> Yeah, I can change them to make them consistent.  I did preserve the
> existing formatting for both, as you mentioned.

Thanks in advance.  This inconsistence just looks strange in one line.

>> I'm not sure if it is a place for it, but the proposed text treats
>> assume-unchanged and skip-worktree as similarly unsuited for intended
>> purpose.  However, their failure modes are different: (ab)using the
>> assume-unchanged for "ignore changed to tracked files" may lead to data
>> loss (as changes are overwritten), while with skip-worktree the trouble
>> is that some operations that should succeed (like unstashing) are
>> unnecessarily blocked - but no data loss.
>
> I agree the failure modes can be different, but from my experience there
> are people who have seen checkout failures with both bits set
> independently.  I'm not exactly sure what those cases are, but folks do
> see them on Stack Overflow quite frequently.
>
> Even if there is a difference in failure modes, I'd rather encourage
> people to just not use this mechanism rather than explain why or in
> which cases it won't do what you want.

What I wanted to say here is that if you really, really need to abuse
those mechanism for "ignore tracked files changes", it is better to use
skip-worktree bit -- at least you wouldn't loose your data (your
precious changes).

Nb. I have experimented with both assume-unchanged and skip-worktree,
so I know their annoyances, but I have not had a need to use them.

>> I would really like to see a simple example of such template, so that
>> even people who are unfamiliar with Ruby's ERB can think of equivalent
>> solution for their language or toolchain of choice.
>
> I hesitated to mention ERB, but I wasn't sure that folks would know what
> we meant by a "templating mechanism".  The reason I had chosen to
> mention it is that someone could search for "Ruby ERB" and find out what
> it looked like and then look for an option in their own language.

I would like to see not an example of template, but example how such
template can be used in place of "ignore tracked files change".

> My concern with adding such a template is that an example will likely
> grow this section quite a bit, and it's meant as a short aside to help
> people avoid making a common mistake and guide them to a proper solution
> rather than a comprehensive howto.  I'm planning on adding a FAQ
> document in the future that covers a lot of these issues in more detail
> and helps folks figure out solutions to common problems, and I'd prefer
> to explain this more in depth there.

Your proposed change:

  +If the file you want to change is some sort of configuration file (say,
  +for a build tool, IDE, or editor), a common solution is to use a
  +templating mechanism, such as Ruby's ERB, to generate the ignored
  +configuration file from a template stored in the repository and a source
  +of data using a script or build step.

I don't see how such templating mechanism could be used.  You have some
kind of configuration file with placeholders comitted, and you have a
version of this file with local changes -- how templating mechanism
could solve this?  I would like to see few lines of an example and its
use.


Alterantives:
~~~~~~~~~~~~~

In our build system, we have versioned Makefile, and not versioned
config.mak (with local configuration), which is included by Makefile.

In many cases using environment variables to provide local changes is
recommended, something like e.g.

  AWS::S3::Base.establish_connection!(
    :access_key_id     => ENV['S3_KEY'],
    :secret_access_key => ENV['S3_SECRET']
  )


Best,
-- 
Jakub Narębski

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 2936 bytes --]

On 2019-11-03 at 19:40:36, Jakub Narebski wrote:
> Your proposed change:
> 
>   +If the file you want to change is some sort of configuration file (say,
>   +for a build tool, IDE, or editor), a common solution is to use a
>   +templating mechanism, such as Ruby's ERB, to generate the ignored
>   +configuration file from a template stored in the repository and a source
>   +of data using a script or build step.
> 
> I don't see how such templating mechanism could be used.  You have some
> kind of configuration file with placeholders comitted, and you have a
> version of this file with local changes -- how templating mechanism
> could solve this?  I would like to see few lines of an example and its
> use.
> 
> Alterantives:
> ~~~~~~~~~~~~~
> 
> In our build system, we have versioned Makefile, and not versioned
> config.mak (with local configuration), which is included by Makefile.

Essentially, make and shell support this by themselves, but if, for
example, I wanted to adjust my dotfiles to set the email address once
and for all, I could create the following files:

.muttrc.erb:
----
my_hdr From: brian m. carlson <<%= data["email"] -%>>
----

.gitconfig.erb:
----
[user]
name = brian m. carlson
email = <%= data["email"] -%>
----

template.rb:
----
#!/usr/bin/env ruby

require 'erb'

class Template
  def name
    @name ||= 0
    @name += 1
    "name_a#{@name}"
  end

  def data
    ENV.map { |k, v| [k.downcase, v] }.to_h
  end

  def erb(file)
    ERB.new(File.read(file), nil, '-', name).result(binding)
  end
end

puts Template.new.erb(ARGV[0])
----

and then run:

EMAIL=sandals@crustytoothpaste.net template.rb .muttrc.erb >.muttrc
EMAIL=sandals@crustytoothpaste.net template.rb .gitconfig.erb >.gitconfig

The problem that folks tend to have is that they have a single editor or
IDE project file, such as an XCode configuration file, that can't be
split among multiple files, some of which are checked in and some of
which are not.  Other situations are generating a configuration file for
a web server like nginx in development, which may of course differ
depending on where the user has checked out the repository.

Using some sort of file like a config.mak is a fine solution, but many
programs don't support that, so it's necessary to create a template for
the build process and add a script to generate it.  The actual
configuration values can come from the environment, the user's
gitconfig, a YAML file the user has configured, or anywhere else that
makes sense.

As you can see, the example is large and unwieldy, and would not make a
good inclusion in the man page.  I included that paragraph because Peff
stated that it would be nice if we could offer people a solution, but
I'd rather drop it if it's too confusing without an example.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]

Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)

[Jeff King]

On Sat, Nov 02, 2019 at 07:26:12PM +0000, brian m. carlson wrote:

> While at one time it made perfect sense to store information about
> configuring author and committer information in the documentation for
> git commit-tree, in modern Git that operation is seldom used.  Most
> users will use git commit and expect to find comprehensive documentation
> about its use in the manual page for that command.
> 
> Considering that there is significant confusion about how one is to use
> the user.name and user.email variables, let's put as much documentation
> as possible into an obvious place where users will be more likely to
> find it.

I think we might want to keep documentation that gets too low-level out
of git-commit(1).

So for instance, this part that got moved from commit-tree:

> +A commit encapsulates:
> +
> +- all parent object ids
> +- author name, email and date
> +- committer name and email and the commit time.
> +

I think could just stay there.

The part just below that:

> +While parent object ids are provided on the command line, author and
> +committer information is taken from the following environment variables,
> +if set:
> +
> +	GIT_AUTHOR_NAME
> +	GIT_AUTHOR_EMAIL
> +	GIT_AUTHOR_DATE
> +	GIT_COMMITTER_NAME
> +	GIT_COMMITTER_EMAIL
> +	GIT_COMMITTER_DATE
> +
> +(nb "<", ">" and "\n"s are stripped)

would be appropriate in git-commit. Though possibly they should just be
broken out into an ENVIRONMENT VARIABLES section.

I thought we already did so in git.txt, but it looks like it just refers
to commit-tree (and if we don't do anything more drastic, I think you'd
probably want to update that reference). Since these do affect multiple
commands, I wonder if it would make sense to define them there in
git.txt, giving a more user-facing description. Something like:

  GIT_COMMITTER_NAME::
	The human-readable name used in the committer identity when
	creating commit or tags objects, or when writing reflogs.
	Overrides the user.name config.

and so forth for COMMITTER_EMAIL, AUTHOR_NAME, etc.

-Peff

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[Jeff King]

On Sun, Nov 03, 2019 at 06:59:08PM +0000, brian m. carlson wrote:

> > I would really like to see a simple example of such template, so that
> > even people who are unfamiliar with Ruby's ERB can think of equivalent
> > solution for their language or toolchain of choice.
> 
> I hesitated to mention ERB, but I wasn't sure that folks would know what
> we meant by a "templating mechanism".  The reason I had chosen to
> mention it is that someone could search for "Ruby ERB" and find out what
> it looked like and then look for an option in their own language.

I don't mind what is here, but I might even suggest going slightly in
the opposite direction. Say something like:

  For example, you the repository can include a sample config file that
  can then be copied into the ignored name and modified.

which points people in the right direction without giving specifics. But
if you did want to go further, you can then say:

  The repository can even include a script to treat the sample file as a
  template, modifying and copying it automatically (e.g., a Ruby script
  using an ERB template).

or something.

> My concern with adding such a template is that an example will likely
> grow this section quite a bit, and it's meant as a short aside to help
> people avoid making a common mistake and guide them to a proper solution
> rather than a comprehensive howto.

Yeah. I don't think we should get into best practices for using ERB.

-Peff

Re: [PATCH v3 0/4] Documentation for common user misconceptions

[Jeff King]

On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:

> This series includes four patches that update the documentation to
> address common user misconceptions.
> 
> Changes from v2:
> * Move author and committer information to git-commit(1) where people
>   will look for it.
> * Move guidance on user.name format to git-commit(1) as well and mention
>   a shortened form of the advice in the `user.name` description.
> * Use a parenthetical to describe a "personal name" without contrasting
>   it with a username.
> * Offer a potential solution for people who want to ignore tracked
>   files by recommending a templating mechanism.
> * Be slightly more verbose about why memory is wasted with
>   http.postBuffer.

Thanks. I think this is an improvement over v1, but I'm still a little
iffy on some of the other movement in the first patch.

TBH, I don't think it's making anything _worse_, but I think it
highlights how some of our documentation is a mish-mash of low-level and
high-level details. ;) So it might be a good opportunity to at least
clean up the documentation around ident environment variables.

-Peff

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1419 bytes --]

On 2019-11-04 at 22:24:16, Jeff King wrote:
> On Sun, Nov 03, 2019 at 06:59:08PM +0000, brian m. carlson wrote:
> 
> > > I would really like to see a simple example of such template, so that
> > > even people who are unfamiliar with Ruby's ERB can think of equivalent
> > > solution for their language or toolchain of choice.
> > 
> > I hesitated to mention ERB, but I wasn't sure that folks would know what
> > we meant by a "templating mechanism".  The reason I had chosen to
> > mention it is that someone could search for "Ruby ERB" and find out what
> > it looked like and then look for an option in their own language.
> 
> I don't mind what is here, but I might even suggest going slightly in
> the opposite direction. Say something like:
> 
>   For example, you the repository can include a sample config file that
>   can then be copied into the ignored name and modified.
> 
> which points people in the right direction without giving specifics. But
> if you did want to go further, you can then say:
> 
>   The repository can even include a script to treat the sample file as a
>   template, modifying and copying it automatically (e.g., a Ruby script
>   using an ERB template).
> 
> or something.

I think this is a nice change.  It summarizes the proposed solution
without needing to be specific.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]

Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

[Jakub Narebski]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:
> On 2019-11-03 at 19:40:36, Jakub Narebski wrote:
>>
>> Your proposed change:
>> 
>>   +If the file you want to change is some sort of configuration file (say,
>>   +for a build tool, IDE, or editor), a common solution is to use a
>>   +templating mechanism, such as Ruby's ERB, to generate the ignored
>>   +configuration file from a template stored in the repository and a source
>>   +of data using a script or build step.
>> 
>> I don't see how such templating mechanism could be used.  You have some
>> kind of configuration file with placeholders comitted, and you have a
>> version of this file with local changes -- how templating mechanism
>> could solve this?  I would like to see few lines of an example and its
>> use.
>> 
>> Alternatives:
>> ~~~~~~~~~~~~~
>> 
>> In our build system, we have versioned Makefile, and not versioned
>> config.mak (with local configuration), which is included by Makefile.
>
> Essentially, make and shell support this by themselves, but if, for
> example, I wanted to adjust my dotfiles to set the email address once
> and for all, I could create the following files:
>
> .muttrc.erb:
> ----
> my_hdr From: brian m. carlson <<%= data["email"] -%>>
> ----
>
> .gitconfig.erb:
> ----
> [user]
> name = brian m. carlson
> email = <%= data["email"] -%>
> ----

All right, the above might be useful as an example (well, one of those),
but might be not necessary if the description of preferred solution is
stated in more detail.  I think it is better to start with generics,
i.e. track template, and generate untracked file, then provide examples
like Ruby's ERB.

> template.rb:
> ----
> #!/usr/bin/env ruby
>
> require 'erb'
>
> class Template
>   def name
>     @name ||= 0
>     @name += 1
>     "name_a#{@name}"
>   end
>
>   def data
>     ENV.map { |k, v| [k.downcase, v] }.to_h
>   end
>
>   def erb(file)
>     ERB.new(File.read(file), nil, '-', name).result(binding)
>   end
> end
>
> puts Template.new.erb(ARGV[0])
> ----

This is certainly too much detail.

> and then run:
>
> EMAIL=sandals@crustytoothpaste.net template.rb .muttrc.erb >.muttrc
> EMAIL=sandals@crustytoothpaste.net template.rb .gitconfig.erb >.gitconfig

That could be kept as an example, after simplification.

> The problem that folks tend to have is that they have a single editor or
> IDE project file, such as an XCode configuration file, that can't be
> split among multiple files, some of which are checked in and some of
> which are not.  Other situations are generating a configuration file for
> a web server like nginx in development, which may of course differ
> depending on where the user has checked out the repository.

All right.

> Using some sort of file like a config.mak is a fine solution, but many
> programs don't support that, so it's necessary to create a template for
> the build process and add a script to generate it.  The actual
> configuration values can come from the environment, the user's
> gitconfig, a YAML file the user has configured, or anywhere else that
> makes sense.

I still think that config.mak (or equivalent) solution might be worth
mentioning in passing.

> As you can see, the example is large and unwieldy, and would not make a
> good inclusion in the man page.  I included that paragraph because Peff
> stated that it would be nice if we could offer people a solution, but
> I'd rather drop it if it's too confusing without an example.

I think it can be done even without example, but without example it
would need careful crafting of the wording.

Best,
-- 
Jakub Narębski

Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I think we might want to keep documentation that gets too low-level out
> of git-commit(1).
>
> So for instance, this part that got moved from commit-tree:
>
>> +A commit encapsulates:
>> +
>> +- all parent object ids
>> +- author name, email and date
>> +- committer name and email and the commit time.
>> +
>
> I think could just stay there.

Me too ;-)

> ... I wonder if it would make sense to define them there in
> git.txt, giving a more user-facing description. Something like:
>
>   GIT_COMMITTER_NAME::
> 	The human-readable name used in the committer identity when
> 	creating commit or tags objects, or when writing reflogs.
> 	Overrides the user.name config.
>
> and so forth for COMMITTER_EMAIL, AUTHOR_NAME, etc.

Yup, I like that.  Then either commit-tree, commit etc. can refer to
the environment variables section of linkgit:git[1], or perhaps assume
that the readers know that anything common across all subcommands
are there in linkgit:git[1] (I prefer the former).

Thanks.

Re: [PATCH v3 0/4] Documentation for common user misconceptions

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Thanks. I think this is an improvement over v1, but I'm still a little
> iffy on some of the other movement in the first patch.
>
> TBH, I don't think it's making anything _worse_, but I think it
> highlights how some of our documentation is a mish-mash of low-level and
> high-level details. ;) So it might be a good opportunity to at least
> clean up the documentation around ident environment variables.

Yeah, I hate to suggest another round, but agree with your comments
on 1/4 wrt the way how and the place where the environment variables
are explained, which invalidates the changes in 2/4.  Fortunately
3/4 and 4/4 are unaffected ;-)

Thanks.

Re: [PATCH v3 0/4] Documentation for common user misconceptions

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1016 bytes --]

On 2019-11-06 at 01:58:33, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> > Thanks. I think this is an improvement over v1, but I'm still a little
> > iffy on some of the other movement in the first patch.
> >
> > TBH, I don't think it's making anything _worse_, but I think it
> > highlights how some of our documentation is a mish-mash of low-level and
> > high-level details. ;) So it might be a good opportunity to at least
> > clean up the documentation around ident environment variables.
> 
> Yeah, I hate to suggest another round, but agree with your comments
> on 1/4 wrt the way how and the place where the environment variables
> are explained, which invalidates the changes in 2/4.  Fortunately
> 3/4 and 4/4 are unaffected ;-)

Yeah, I agree another round is warranted, and it's not the end of the
world: it'll get into 2.25 either way.  I'll try to get a reroll out in
the next few days.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]

Re: [PATCH v3 0/4] Documentation for common user misconceptions

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> On 2019-11-06 at 01:58:33, Junio C Hamano wrote:
>> Jeff King <peff@peff.net> writes:
>> 
>> > Thanks. I think this is an improvement over v1, but I'm still a little
>> > iffy on some of the other movement in the first patch.
>> >
>> > TBH, I don't think it's making anything _worse_, but I think it
>> > highlights how some of our documentation is a mish-mash of low-level and
>> > high-level details. ;) So it might be a good opportunity to at least
>> > clean up the documentation around ident environment variables.
>> 
>> Yeah, I hate to suggest another round, but agree with your comments
>> on 1/4 wrt the way how and the place where the environment variables
>> are explained, which invalidates the changes in 2/4.  Fortunately
>> 3/4 and 4/4 are unaffected ;-)
>
> Yeah, I agree another round is warranted, and it's not the end of the
> world: it'll get into 2.25 either way.  I'll try to get a reroll out in
> the next few days.

Thanks.  I also agree with what Peff and you said on 3/4 wrt the
addition of "ship template, tweak it into an untracked config that
gets used".

Re: [PATCH v3 0/4] Documentation for common user misconceptions

[Emily Shaffer]

On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:
> This series includes four patches that update the documentation to
> address common user misconceptions.

Hm, is this still waiting for a reroll? Someone just ran into the
user.name/username confusion in #git-devel today:
https://colabti.org/irclogger/irclogger_log/git-devel?date=2020-01-16#l79

 - Emily

Re: [PATCH v3 0/4] Documentation for common user misconceptions

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 602 bytes --]

On 2020-01-16 at 21:08:57, Emily Shaffer wrote:
> On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:
> > This series includes four patches that update the documentation to
> > address common user misconceptions.
> 
> Hm, is this still waiting for a reroll? Someone just ran into the
> user.name/username confusion in #git-devel today:
> https://colabti.org/irclogger/irclogger_log/git-devel?date=2020-01-16#l79

Yeah, it is.  I have one, but haven't sent it out.  I'll plan to do so
this weekend.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]