Documentation for common user misconceptions
v3 cover Documentation for common user misconceptions
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.
+
## 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)
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.
--- Documentation/config/user.txt | 2 +- Documentation/git-commit-tree.txt | 39 ++++--------------------------- Documentation/git-commit.txt | 34 ++++++++++++++++++++++++--- 3 files changed, 37 insertions(+), 38 deletions(-)
Documentation/config/user.txt +1 -1
@@ -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`
Documentation/git-commit-tree.txt +5 -34
@@ -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 ---
Documentation/git-commit.txt +31 -3
@@ -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 ----------
Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)
Quoted 23 lines · 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 <[email protected]>--- Documentation/config/user.txt | 2 +- Documentation/git-commit-tree.txt | 39 ++++--------------------------- Documentation/git-commit.txt | 34 ++++++++++++++++++++++++--- 3 files changed, 37 insertions(+), 38 deletions(-)Documentation/config/user.txt +0
-0
Documentation/config/user.txt committer.email:: · line 16
Quoted 5 lines
Documentation/config/user.txt +1
-1@@ -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.
Quoted 7 lines
Documentation/config/user.txt +0
-0user.useConfigOnly:: Instruct Git to avoid trying to guess defaults for `user.email`Documentation/git-commit-tree.txt +0
-0
Documentation/git-commit-tree.txt tend to just write the result to the file that is pointed at by · line 48
Quoted 7 lines
Documentation/git-commit-tree.txt +4
-0@@ -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.
Quoted 6 lines
Documentation/git-commit-tree.txt +0
-0OPTIONS ------- <tree>::@@ -69,40 +73,6 @@ OPTIONS Do not GPG-sign commit, to countermand a `--gpg-sign` option given earlier on the command line.
Documentation/git-commit-tree.txt OPTIONS · line 80
Quoted 10 lines
Documentation/git-commit-tree.txt +0
-9- -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?).
Quoted 10 lines
Documentation/git-commit-tree.txt +0
-10- -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
Documentation/git-commit-tree.txt OPTIONS · line 100
Quoted 10 lines
Documentation/git-commit-tree.txt +0
-10- 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?
Documentation/git-commit-tree.txt FILES · line 90
Quoted 13 lines
Documentation/git-commit-tree.txt +1
-5- -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.
Quoted 8 lines
Documentation/git-commit-tree.txt +0
-0GIT ---Documentation/git-commit.txt +0
-0
Documentation/git-commit.txt changes to tracked files. · line 357
Quoted 6 lines
Documentation/git-commit.txt +0
-3@@ -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.
Quoted 7 lines
Documentation/git-commit.txt +0
-0EXAMPLES -------- 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).
Documentation/git-commit.txt alter the order the changes are committed, because the merge · line 457
Quoted 10 lines
Documentation/git-commit.txt +10
-0+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.
Quoted 9 lines
Documentation/git-commit.txt +8
-0author 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
Documentation/git-commit.txt alter the order the changes are committed, because the merge · line 475
Quoted 10 lines
Documentation/git-commit.txt +10
-0+ 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?
Quoted 6 lines
Documentation/git-commit.txt +3
-0+ +:git-commit: 1 +include::date-formats.txt[] DISCUSSION----------
Best,
Signature · 1 line
Jakub Narębski
Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)
In reply to brian m. carlsonQuoted 10 lines · 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.
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:
Documentation/git-commit.txt alter the order the changes are committed, because the merge · line 456
Quoted 6 lines
Documentation/git-commit.txt +6
-0+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:
Documentation/git-commit.txt alter the order the changes are committed, because the merge · line 468
Quoted 12 lines
Documentation/git-commit.txt +12
-0+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 1/4] doc: move author and committer information to git-commit(1)
Quoted 5 lines · Jeff King
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:
Quoted 8 lines
Documentation/git-commit.txt alter the order the changes are committed, because the merge · line 456
Quoted 6 lines
Documentation/git-commit.txt +6
-0+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 ;-)
Quoted 9 lines
... 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.
PATCH v3 2/4 doc: provide guidance on user.name format
In reply to brian m. carlsonIt'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.
--- Documentation/config/user.txt | 7 ++++++- Documentation/git-commit.txt | 6 ++++++ 2 files changed, 12 insertions(+), 1 deletion(-)
Documentation/config/user.txt +6 -1
@@ -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`
Documentation/git-commit.txt +6 -0
@@ -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,
Re: [PATCH v3 2/4] doc: provide guidance on user.name format
Quoted 7 lines · 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.
Quoted 6 lines
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
Quoted 6 lines
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 <[email protected]>
I like this change! Un-confusing users is always a win.
Quoted 10 lines
--- Documentation/config/user.txt | 7 ++++++- Documentation/git-commit.txt | 6 ++++++ 2 files changed, 12 insertions(+), 1 deletion(-)Documentation/config/user.txt +0
-0
Documentation/config/user.txt committer.email:: · line 21
Quoted 10 lines
Documentation/config/user.txt +6
-1@@ -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.
Quoted 8 lines
Documentation/config/user.txt +0
-0user.useConfigOnly:: Instruct Git to avoid trying to guess defaults for `user.email`Documentation/git-commit.txt +0
-0
Documentation/git-commit.txt if set: · line 474
Quoted 8 lines
Documentation/git-commit.txt +5
-0@@ -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?
Documentation/git-commit.txt if set: · line 478
Quoted 4 lines
Documentation/git-commit.txt +1
-0+ 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,
Signature · 1 line
Jakub Narębski
Re: [PATCH v3 2/4] doc: provide guidance on user.name format
Quoted 2 lines · Jakub Narebski
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.
Quoted 4 lines
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.
Quoted 2 lines
Just ensuring that I understand it correctly: by "constraints" you mean stripping of "<", ">" and "\n" (and by implication "\0")?
Yes, that's correct.
Quoted 1 line
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.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
PATCH v3 3/4 doc: dissuade users from trying to ignore tracked files
In reply to brian m. carlsonIt 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.
--- Documentation/git-update-index.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)
Documentation/git-update-index.txt +16 -0
@@ -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],
RE: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
Quoted 1 line · brian m. carlson
It is quite common for users to want to ignore the changes to a file that
Git
Quoted 11 lines
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
Quoted 3 lines
data that the user would be happy to discard.
Since this is not a supported configuration and users are prone to misuse
the
Quoted 8 lines
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 3/4] doc: dissuade users from trying to ignore tracked files
Quoted 10 lines · <[email protected]> writes:
Quoted 9 lines · 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.
[...]
Quoted 9 lines
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 begit add -f, sogit add .andgit commit -awould 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).
Quoted 3 lines
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,
Signature · 1 line
Jakub Narębski
Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
In reply to brian m. carlsonQuoted 20 lines · 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.
Quoted 3 lines
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.
Quoted 10 lines
Signed-off-by brian m. carlson <[email protected]>--- Documentation/git-update-index.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)Documentation/git-update-index.txt +0
-0
Documentation/git-update-index.txt The untracked cache extension can be enabled by the · line 549
Quoted 7 lines
Documentation/git-update-index.txt +4
-0@@ -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.
Documentation/git-update-index.txt The untracked cache extension can be enabled by the · line 554
Quoted 5 lines
Documentation/git-update-index.txt +5
-0+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.
Documentation/git-update-index.txt The untracked cache extension can be enabled by the · line 560
Quoted 6 lines
Documentation/git-update-index.txt +6
-0+ +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.
Documentation/git-update-index.txt The untracked cache extension can be enabled by the · line 564
Quoted 4 lines
Documentation/git-update-index.txt +1
-0+ SEE ALSO -------- linkgit:git-config[1],
Best,
Signature · 1 line
Jakub Narębski
Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
Quoted 11 lines · Jakub Narebski
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
------------------------------
Quoted 7 lines
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.
Quoted 7 lines
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.
Quoted 3 lines
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.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
Quoted 15 lines · brian m. carlson
Quoted 13 lines · Jakub Narebski
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
Quoted 8 lines
Quoted 5 lines
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.
Quoted 8 lines
Quoted 7 lines
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.
Quoted 8 lines
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.
Quoted 8 lines
Quoted 3 lines
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".
Quoted 7 lines
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,
Signature · 1 line
Jakub Narębski
Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
Quoted 14 lines · Jakub Narebski
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.
Quoted 5 lines
Alterantives:
~~~~~~~~~~~~~In our build system, we have versioned
Makefile, and not versioned config.mak (with local configuration), which is included byMakefile.
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_hend
def erb(file)
ERB.new(File.read(file), nil, '-', name).result(binding)
end
end
puts Template.new.erb(ARGV[0])
----
and then run:
[email protected] template.rb .muttrc.erb >.muttrc [email protected] 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.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
Quoted 31 lines · brian m. carlson
Quoted 15 lines · Jakub Narebski
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.
Quoted 5 lines
Alternatives:
~~~~~~~~~~~~~In our build system, we have versioned
Makefile, and not versioned config.mak (with local configuration), which is included byMakefile.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_hdrFrom: brian m. carlson <<%= data["email"] -%>>
----
Quoted 6 lines
.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.
Quoted 17 lines
template.rb:
----
#!/usr/bin/env rubyrequire 'erb'
class Template
def name@name ||= 0 @name += 1 "name_a#{@name}"end
def data
ENV.map { |k, v| [k.downcase, v] }.to_hend
Quoted 7 lines
def erb(file)
ERB.new(File.read(file), nil, '-', name).result(binding)end
endputs
Template.new.erb(ARGV[0])
----
This is certainly too much detail.
Quoted 4 lines
and then run:
[email protected] template.rb .muttrc.erb >.muttrc [email protected] template.rb .gitconfig.erb >.gitconfig
That could be kept as an example, after simplification.
Quoted 6 lines
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.
Quoted 6 lines
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.
Quoted 4 lines
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,
Signature · 1 line
Jakub Narębski
Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files
In reply to brian m. carlsonQuoted 8 lines · brian m. carlson
Quoted 3 lines
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.
Quoted 4 lines
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 3/4] doc: dissuade users from trying to ignore tracked files
Quoted 17 lines · Jeff King
Quoted 8 lines · brian m. carlson
Quoted 3 lines
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.
Quoted 8 lines
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.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
PATCH v3 4/4 docs: mention when increasing http.postBuffer is valuable
In reply to brian m. carlsonUsers 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.
--- Documentation/config/http.txt | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/config/http.txt +8 -0
@@ -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'
Quoted 14 lines · 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 theuser.namedescription.
* 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
Quoted 7 lines · Jeff King
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.
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Jeff King
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.
Quoted 4 lines
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.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Quoted 11 lines · brian m. carlson
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Jeff King
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.
Quoted 8 lines
Quoted 4 lines
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".
Quoted 2 lines · brian m. carlson
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
Quoted 7 lines · Emily Shaffer
Quoted 2 lines · brian m. carlson
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.
Signature · 2 lines
brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204