Documentation: add caveats about I/O buffering for check-{attr,ignore}

diff --git a/setup.c b/setup.c
index 994976946b4b451ee41508a2649987c9b4e9bdbc..95701475d58dcf9dd169ae0e07a1003018f19129 100644 (file)
--- a/setup.c
+++ b/setup.c
@@ -4,7 +4,7 @@
 static int inside_git_dir = -1;
 static int inside_work_tree = -1;
 
-char *prefix_path(const char *prefix, int len, const char *path)
+static char *prefix_path_gently(const char *prefix, int len, const char *path)
 {
        const char *orig = path;
        char *sanitized;
@@ -31,7 +31,8 @@ char *prefix_path(const char *prefix, int len, const char *path)
                if (strncmp(sanitized, work_tree, len) ||
                    (len > root_len && sanitized[len] != '\0' && sanitized[len] != '/')) {
                error_out:
-                       die("'%s' is outside repository", orig);
+                       free(sanitized);
+                       return NULL;
                }
                if (sanitized[len] == '/')
                        len++;
@@ -40,6 +41,25 @@ char *prefix_path(const char *prefix, int len, const char *path)
        return sanitized;
 }
 
+char *prefix_path(const char *prefix, int len, const char *path)
+{
+       char *r = prefix_path_gently(prefix, len, path);
+       if (!r)
+               die("'%s' is outside repository", path);
+       return r;
+}
+
+int path_inside_repo(const char *prefix, const char *path)
+{
+       int len = prefix ? strlen(prefix) : 0;
+       char *r = prefix_path_gently(prefix, len, path);
+       if (r) {
+               free(r);
+               return 1;
+       }
+       return 0;
+}
+
 int check_filename(const char *prefix, const char *arg)
 {
        const char *name;
@@ -62,7 +82,7 @@ static void NORETURN die_verify_filename(const char *prefix,
 
        if (!diagnose_misspelt_rev)
                die("%s: no such path in the working tree.\n"
-                   "Use '-- <path>...' to specify paths that do not exist locally.",
+                   "Use 'git <command> -- <path>...' to specify paths that do not exist locally.",
                    arg);
        /*
         * Saying "'(icase)foo' does not exist in the index" when the
@@ -76,7 +96,8 @@ static void NORETURN die_verify_filename(const char *prefix,
 
        /* ... or fall back the most general message. */
        die("ambiguous argument '%s': unknown revision or path not in the working tree.\n"
-           "Use '--' to separate paths from revisions", arg);
+           "Use '--' to separate paths from revisions, like this:\n"
+           "'git <command> [<revision>...] -- [<file>...]'", arg);
 
 }
 
@@ -125,7 +146,8 @@ void verify_non_filename(const char *prefix, const char *arg)
        if (!check_filename(prefix, arg))
                return;
        die("ambiguous argument '%s': both revision and filename\n"
-           "Use '--' to separate filenames from revisions", arg);
+           "Use '--' to separate paths from revisions, like this:\n"
+           "'git <command> [<revision>...] -- [<file>...]'", arg);
 }
 
 /*
@@ -227,6 +249,25 @@ static const char *prefix_pathspec(const char *prefix, int prefixlen, const char
                return prefix_path(prefix, prefixlen, copyfrom);
 }
 
+/*
+ * N.B. get_pathspec() is deprecated in favor of the "struct pathspec"
+ * based interface - see pathspec_magic above.
+ *
+ * Arguments:
+ *  - prefix - a path relative to the root of the working tree
+ *  - pathspec - a list of paths underneath the prefix path
+ *
+ * Iterates over pathspec, prepending each path with prefix,
+ * and return the resulting list.
+ *
+ * If pathspec is empty, return a singleton list containing prefix.
+ *
+ * If pathspec and prefix are both empty, return an empty list.
+ *
+ * This is typically used by built-in commands such as add.c, in order
+ * to normalize argv arguments provided to the built-in into a list of
+ * paths to process, all relative to the root of the working tree.
+ */
 const char **get_pathspec(const char *prefix, const char **pathspec)
 {
        const char *entry = *pathspec;