Jeff King <peff@xxxxxxxx> writes: > On Mon, Nov 27, 2017 at 12:24:43AM -0500, Jeff King wrote: > >> > If people have to ask on the mailing list even after reading the man >> > pages, that's a strong indicator that we could do better. >> >> Sure. That's why I suggested improving the documentation in my last >> email. But in all the discussion, I haven't seen any patch to that >> effect. > > Maybe like this. I gave it only a single read, and it was a quite easy read. Will queue but not immediately merge to 'next' before I hear from others. Thanks. > -- >8 -- > Subject: [PATCH] git-status.txt: mention --no-optional-locks > > If you come to the documentation thinking "I do not want Git > to take any locks for my background processes", then you may > easily run across "--no-optional-locks" in git.txt. > > But it's quite reasonable to hit a specific instance of the > problem: you have "git status" running in the background, > and you notice that it causes lock contention with other > processes. So you look in git-status.txt to see if there is > a way to disable it, but there's no mention of the flag. > > Let's add a short note mentioning that status does indeed > touch the index (and why), with a pointer to the global > option. That can point users in the right direction and help > them make a more informed decision about what they're > disabling. > > Signed-off-by: Jeff King <peff@xxxxxxxx> > --- > Documentation/git-status.txt | 13 +++++++++++++ > 1 file changed, 13 insertions(+) > > diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt > index fc282e0a92..81cab9aefb 100644 > --- a/Documentation/git-status.txt > +++ b/Documentation/git-status.txt > @@ -387,6 +387,19 @@ ignored submodules you can either use the --ignore-submodules=dirty command > line option or the 'git submodule summary' command, which shows a similar > output but does not honor these settings. > > +BACKGROUND REFRESH > +------------------ > + > +By default, `git status` will automatically refresh the index, updating > +the cached stat information from the working tree and writing out the > +result. Writing out the updated index is an optimization that isn't > +strictly necessary (`status` computes the values for itself, but writing > +them out is just to save subsequent programs from repeating our > +computation). When `status` is run in the background, the lock held > +during the write may conflict with other simultaneous processes, causing > +them to fail. Scripts running `status` in the background should consider > +using `git --no-optional-locks status` (see linkgit:git[1] for details). > + > SEE ALSO > -------- > linkgit:gitignore[5]
