sha1-file: document how to use pretend_object_file

Like in-memory alternates, pretend_object_file contains a trap for the
unwary: careless callers can use it to create references to an object
that does not exist in the on-disk object store.

Add a comment documenting how to use the function without risking such
problems.

The only current caller is blame, which uses pretend_object_file to
create an in-memory commit representing the working tree state.
Noticed during a discussion of how to safely use this function in
operations like "git merge" which, unlike blame, are not read-only.

Inspired-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/object-store.h b/object-store.h
index 7f7b3cdd806b756eefb86c7d116ba9a9a6c62558..f91e0c99b48f3e69de96bc0206bd698c39ffe25c 100644 (file)
--- a/object-store.h
+++ b/object-store.h
@@ -187,6 +187,14 @@ int hash_object_file_literally(const void *buf, unsigned long len,
                               const char *type, struct object_id *oid,
                               unsigned flags);
 
+/*
+ * Add an object file to the in-memory object store, without writing it
+ * to disk.
+ *
+ * Callers are responsible for calling write_object_file to record the
+ * object in persistent storage before writing any other new objects
+ * that reference it.
+ */
 int pretend_object_file(void *, unsigned long, enum object_type,
                        struct object_id *oid);