| Message ID | 20191102192615.10013-1-sandals@crustytoothpaste.net (mailing list archive) |
|---|---|
| Headers | show |
| Series | Documentation for common user misconceptions | expand |
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
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.
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" <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".
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
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.
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'