Add a test for --intend-to-add and clarify what this flag means.

Author: Byron

gix-index/src/entry/flags.rs

@@ -3,25 +3,27 @@ use bitflags::bitflags;
 use crate::entry::Stage;
 
 bitflags! {
-    /// In-memory flags
+    /// In-memory flags.
+    ///
+    /// Notably, not all of these will be persisted but can be used to aid all kinds of operations.
     #[derive(Debug, Clone, Copy, Eq, PartialEq)]
     pub struct Flags: u32 {
-        /// The mask to apply to obtain the stage number of an entry.
-        const STAGE_MASK = 0x3000;
-        /// If set, additional bits need to be written to storage.
-        const EXTENDED = 0x4000;
         // TODO: could we use the pathlen ourselves to save 8 bytes? And how to handle longer paths than that? 0 as sentinel maybe?
-        /// The mask to obtain the length of the path associated with this entry.
+        /// The mask to obtain the length of the path associated with this entry, up to 4095 characters without extension.
         const PATH_LEN = 0x0fff;
+        /// The mask to apply to obtain the stage number of an entry, encoding three value: 0 = base, 1 = ours, 2 = theirs.
+        const STAGE_MASK = 1<<12 | 1<<13;
+        /// If set, additional bits need to be written to storage.
+        const EXTENDED = 1<<14;
         /// If set, the entry be assumed to match with the version on the working tree, as a way to avoid `lstat()`  checks.
         const ASSUME_VALID = 1 << 15;
         /// Indicates that an entry needs to be updated as it's in-memory representation doesn't match what's on disk.
         const UPDATE = 1 << 16;
         /// Indicates an entry should be removed - this typically happens during writing, by simply skipping over them.
         const REMOVE = 1 << 17;
-        /// Indicates that an entry is known to be uptodate.
+        /// Indicates that an entry is known to be up-to-date.
         const UPTODATE = 1 << 18;
-        /// Only temporarily used by unpack_trees() (in C)
+        /// Only temporarily used by unpack_trees() (in C).
         const ADDED = 1 << 19;
 
         /// Whether an up-to-date object hash exists for the entry.
@@ -46,8 +48,8 @@ bitflags! {
         /// Indicates the entry name is present in the base/shared index, and thus doesn't have to be stored in this one.
         const STRIP_NAME = 1 << 28;
 
-        ///
-        /// stored at rest, see at_rest::FlagsExtended
+        /// Created with `git add --intent-to-add` to mark empty entries that have their counter-part in the worktree, but not
+        /// yet in the object database.
         const INTENT_TO_ADD = 1 << 29;
         /// Stored at rest
         const SKIP_WORKTREE = 1 << 30;
@@ -102,7 +104,7 @@ pub(crate) mod at_rest {
 
     bitflags! {
         /// Extended flags - add flags for serialization here and offset them down to u16.
-        #[derive(Copy, Clone, Debug)]
+        #[derive(Copy, Clone, Debug, PartialEq)]
         pub struct FlagsExtended: u16 {
             const INTENT_TO_ADD = 1 << (29 - 16);
             const SKIP_WORKTREE = 1 << (30 - 16);
@@ -124,6 +126,18 @@ pub(crate) mod at_rest {
     mod tests {
         use super::*;
 
+        #[test]
+        fn flags_extended_conversion() {
+            assert_eq!(
+                FlagsExtended::all().to_flags(),
+                Some(super::super::Flags::INTENT_TO_ADD | super::super::Flags::SKIP_WORKTREE)
+            );
+            assert_eq!(
+                FlagsExtended::from_flags(super::super::Flags::all()),
+                FlagsExtended::all()
+            );
+        }
+
         #[test]
         fn flags_from_bits_with_conflict() {
             let input = 0b1110_0010_1000_1011;

gix-index/tests/fixtures/generated-archives/v3_added_files.tar.xz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ee69ff44520a277ed76b928c5e19986310f5628ca09f46e62f6b1eb73d310a2c
+size 9288

gix-index/tests/fixtures/generated-archives/v3_skip_worktree.tar.xz

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:105298714e7ee6b7c58b702cec3d4ff13b7488732c6389602b5b349a38da61e8
-size 10632
+oid sha256:5b507facc0ca80e92997a75cd6f53c8e13da1582cac52ad202949a8af3f0491b
+size 9308

gix-index/tests/fixtures/make_index/v3_added_files.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -eu -o pipefail
+
+git init -q
+
+touch a
+git add --intent-to-add a

gix-index/tests/index/file/read.rs

@@ -6,6 +6,7 @@ use gix_index::{
     Version,
 };
 
+use crate::index::Fixture;
 use crate::{hex_to_id, loose_file_path};
 
 fn verify(index: gix_index::File) -> gix_index::File {
@@ -186,6 +187,14 @@ fn fsmn_v1() {
     assert!(file.fs_monitor().is_some());
 }
 
+#[test]
+fn v3_added_files() {
+    let file = Fixture::Generated("v3_added_files").open();
+    assert_eq!(file.version(), Version::V3, "uses extended attributes");
+    assert_eq!(file.entries().len(), 1);
+    assert_eq!(file.entries()[0].flags, Flags::EXTENDED | Flags::INTENT_TO_ADD);
+}
+
 #[test]
 fn file_with_conflicts() {
     let file = loose_file("conflicting-file");

gix-index/tests/index/file/write.rs

@@ -96,6 +96,7 @@ fn state_comparisons_with_various_extension_configurations() {
         //       the fixture artificially sets the version to V4 and gitoxide writes it back out as the lowest required version, V2
         // Generated("v4_more_files_IEOT"),
         Generated("v3_skip_worktree"),
+        Generated("v3_added_files"),
         Generated("v3_sparse_index_non_cone"),
         Generated("v3_sparse_index"),
         // TODO: this fails because git writes the sdir extension in this case while gitoxide doesn't