Re: [PATCHv2 3/4] cache.h: document add_[file_]to_index

On Wed, Jan 18, 2017 at 4:00 PM, Brandon Williams [off-list ref] wrote:

On 01/18, Stefan Beller wrote:

quoted

Signed-off-by: Stefan Beller <redacted>
---
 cache.h | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/cache.h b/cache.h
index 87eccdb211..03c46b9b99 100644
--- a/cache.h
+++ b/cache.h

@@ -609,13 +609,24 @@ extern int remove_index_entry_at(struct index_state *, int pos);

 extern void remove_marked_cache_entries(struct index_state *istate);
 extern int remove_file_from_index(struct index_state *, const char *path);
-#define ADD_CACHE_VERBOSE 1
-#define ADD_CACHE_PRETEND 2
-#define ADD_CACHE_IGNORE_ERRORS      4
-#define ADD_CACHE_IGNORE_REMOVAL 8
-#define ADD_CACHE_INTENT 16
+
+#define ADD_CACHE_VERBOSE 1          /* verbose */
+#define ADD_CACHE_PRETEND 2          /* dry run */
+#define ADD_CACHE_IGNORE_ERRORS 4    /* ignore errors */
+#define ADD_CACHE_IGNORE_REMOVAL 8   /* do not remove files from index */
+#define ADD_CACHE_INTENT 16          /* intend to add later; stage empty file */

I usually prefer having defines like these use shift operators to set
the desired bit '(1<<2)' instead of '4', etc.  Is there a preference for
git as a whole?  I know this is just a documentation change so maybe
this isn't even the place to discuss this.

eh, and I forgot to remove the comments that Junio thought of as redundant.
I agree that (1<<N)) is usually better than the actual number. But I think
we do not want to change that for the same reason as we don't want to add
these comments there: Digging into history just got more complicated here.
("Who introduced ADD_CACHE_INTENT and why?" you need to skip the
reformatting/adding document patch to actually find the answer.)

Thanks for spotting,
Stefan

--
Brandon Williams