checkout_entry(): clarify the use of topath[] parameter

The said function has this signature:

extern int checkout_entry(struct cache_entry *ce,
const struct checkout *state,
char *topath);

At first glance, it might appear that the caller of checkout_entry()
can specify to which path the contents are written out by the last
parameter, and it is tempting to add "const" in front of its type.

In reality, however, topath[] is to point at a buffer to store the
temporary path generated by the callchain originating from this
function, and the temporary path is always short, much shorter than
the buffer prepared by its only caller in builtin/checkout-index.c.

Document the code a bit to clarify so that future callers know how
to use the function better.

Noticed-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/builtin/checkout-index.c b/builtin/checkout-index.c
index b1feda7d5ef34f45ed2de018a56149212b51ec0a..4ed6b23954f27269a219fab3c69ca9bf16227aa4 100644 (file)
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -14,7 +14,7 @@
 static int line_termination = '\n';
 static int checkout_stage; /* default to checkout stage0 */
 static int to_tempfile;
-static char topath[4][PATH_MAX + 1];
+static char topath[4][TEMPORARY_FILENAME_LENGTH + 1];
 
 static struct checkout state;
 

diff --git a/cache.h b/cache.h
index 85b544f38d934fe68d1e155c86337f1400eea14d..3118b7fc993a1df37ae608390696cf7eb700a757 100644 (file)
--- a/cache.h
+++ b/cache.h
@@ -975,6 +975,7 @@ struct checkout {
                 refresh_cache:1;
 };
 
+#define TEMPORARY_FILENAME_LENGTH 25
 extern int checkout_entry(struct cache_entry *ce, const struct checkout *state, char *topath);
 
 struct cache_def {

diff --git a/entry.c b/entry.c
index fbb4863103417a408f11f9b5141b833915b2b211..7b7aa8167adade20f38cfb2709e02b3ed31f11a4 100644 (file)
--- a/entry.c
+++ b/entry.c
@@ -234,6 +234,14 @@ static int check_path(const char *path, int len, struct stat *st, int skiplen)
        return lstat(path, st);
 }
 
+/*
+ * Write the contents from ce out to the working tree.
+ *
+ * When topath[] is not NULL, instead of writing to the working tree
+ * file named by ce, a temporary file is created by this function and
+ * its name is returned in topath[], which must be able to hold at
+ * least TEMPORARY_FILENAME_LENGTH bytes long.
+ */
 int checkout_entry(struct cache_entry *ce,
                   const struct checkout *state, char *topath)
 {