On 03/15/2013 05:53 PM, Junio C Hamano wrote:
Torsten Bögershausen<tbo...@web.de>  writes:

[PATCH] git status: Document that git status -uno is faster

In some repostories users expere that "git status" command takes long time.
expere???  Certainly you did not mean "expect".  "observe",
"experience", or "see", perhaps?

The command spends some time searching the file system for untracked files.
Document that searching for untracked file may take some time, and docuemnt
the option -uno better.
Good intentions.

Signed-off-by: Torsten Bögershausen<tbo...@web.de>
---
  Documentation/git-status.txt | 7 +++++++
  1 file changed, 7 insertions(+)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 0412c40..fd36bbd 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -58,6 +58,13 @@ The possible options are:
  The default can be changed using the status.showUntrackedFiles
  configuration variable documented in linkgit:git-config[1].

++
+Note: Searching the file system for untracked files may take some time.
+git status -uno is faster than git status -uall.
+There is a trade-off around the use of -uno between safety and performance.
+The default is not to use -uno so that you will not forget to add a
file you newly created (i.e safety).
+You would pay for the safety with the cost to find such untracked
files (i.e. performance).
+
The second sentence looks out of flow, and the last sentence, while
technically not incorrect, is unclear what it is trying to convey in
the larger picture.

Perhaps it is just me.

In any case, I think it is a good idea to explain the reason why the
user might want to use a non-default setting, and the criteria the
user may want to base the choice on (which is the gist of your
addition), and it is a good idea to do so _before_ saying "The
default can be changed using ...".

How about this?

  Documentation/git-status.txt | 14 ++++++++++----
  1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 0412c40..9046df9 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -46,15 +46,21 @@ OPTIONS
        Show untracked files.
  +
  The mode parameter is optional (defaults to 'all'), and is used to
-specify the handling of untracked files; when -u is not used, the
-default is 'normal', i.e. show untracked files and directories.
+specify the handling of untracked files.
  +
  The possible options are:
  +
-       - 'no'     - Show no untracked files
-       - 'normal' - Shows untracked files and directories
+       - 'no'     - Show no untracked files.
+       - 'normal' - Shows untracked files and directories.
        - 'all'    - Also shows individual files in untracked directories.
  +
+When `-u` option is not used, untracked files and directories are
+shown (i.e. the same as specifying `normal`), to help you avoid
+forgetting to add newly created files.  Because it takes extra work
+to find untracked files in the filesystem, this mode may take some
+time in a large working tree.  You can use `no` to have `git status`
(Small nit: extra space before the "You" in the line above)

Thanks, I like that much better than mine
(and expere is probably a word not yet invented)
/Torsten

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to