commit - ef99fdb1099b987bfaed49367904342f77da3e43
commit + 58ecc593d87b44c67285aa8e2fb9ae755dcb212a
blob - bf96dcd4879054c26ee1e328864c6fe76ffceaff
blob + 7a450583547cf98b71421a004139b893da9708a7
--- lib/got_worktree_priv.h
+++ lib/got_worktree_priv.h
@@ -20,8 +20,16 @@ struct got_worktree {
 	char *path_prefix;
 
 	/*
-	 * This file descriptor exclusively locks GOT_WORKTREE_FILE_INDEX.
-	 * This ensures that only one process opens the work tree at a time.
+	 * File descriptor for the file index, open while a work tree is open.
+	 * This is used to read the file index and to write out a new file
+	 * index, and also for locking the entire work tree.
+	 * When a work tree is opened, a shared lock on the file index is
+	 * acquired with flock(2). This shared lock is held until the work
+	 * tree is closed, i.e. throughout the lifetime of any operation
+	 * which uses a work tree.
+	 * Before any modifications are made to the on-disk state of meta data,
+	 * tracked files, or directory tree structure, this shared lock must
+	 * be upgraded to an exclusive lock.
 	 */
 	int fd_fileindex;
 };