git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jeff King <peff@peff.net>
To: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Cc: Junio C Hamano <gitster@pobox.com>,
	Jonathan Nieder <jrnieder@gmail.com>,
	Nathan Neulinger <nneul@neulinger.org>,
	Santiago Torres <santiago@nyu.edu>,
	git@vger.kernel.org
Subject: [PATCH] git-status.txt: mention --no-optional-locks
Date: Mon, 27 Nov 2017 01:04:12 -0500	[thread overview]
Message-ID: <20171127060412.GA1247@sigill> (raw)
In-Reply-To: <20171127052443.GB5946@sigill>

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.

-- >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@peff.net>
---
 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]
-- 
2.15.0.687.g5a800c9f78


  parent reply	other threads:[~2017-11-27  6:04 UTC|newest]

Thread overview: 33+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-11-22 15:19 git status always modifies index? Nathan Neulinger
2017-11-22 15:30 ` Santiago Torres
2017-11-22 15:37   ` Nathan Neulinger
2017-11-22 16:10     ` Santiago Torres
2017-11-22 16:20       ` Nathan Neulinger
2017-11-22 16:24         ` Santiago Torres
2017-11-22 20:27         ` Jonathan Nieder
2017-11-22 21:17           ` Jeff King
2017-11-22 21:56             ` Jonathan Nieder
2017-11-22 22:06               ` Jeff King
2017-11-25 21:55                 ` Johannes Schindelin
2017-11-26 19:25                   ` Jeff King
2017-11-26 21:55                     ` Johannes Schindelin
2017-11-27  5:24                       ` Jeff King
2017-11-27  6:03                         ` Junio C Hamano
2017-11-27 20:50                           ` Johannes Schindelin
2017-11-27  6:04                         ` Jeff King [this message]
2017-11-27  6:07                           ` [PATCH] git-status.txt: mention --no-optional-locks Junio C Hamano
2017-11-27 10:22                             ` Kaartic Sivaraam
2017-11-27 20:54                               ` Johannes Schindelin
2017-11-27 20:44                         ` git status always modifies index? Johannes Schindelin
2017-11-27 20:49                           ` Jonathan Nieder
2017-11-26  3:32                 ` Junio C Hamano
2017-11-26  9:35                   ` Junio C Hamano
2017-11-27  4:43                     ` Jeff King
2017-11-27  4:56                       ` Junio C Hamano
2017-11-27  5:00                         ` Jeff King
2017-11-27 20:57                       ` Jonathan Nieder
2017-11-27 22:50                         ` Jeff King
2017-12-03  0:37                         ` Junio C Hamano
2017-11-26 19:27                   ` Jeff King
2017-11-27  0:47                     ` Junio C Hamano
2017-11-27  6:12                       ` Jeff King

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20171127060412.GA1247@sigill \
    --to=peff@peff.net \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=jrnieder@gmail.com \
    --cc=nneul@neulinger.org \
    --cc=santiago@nyu.edu \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).