git-internal 0.8.4

High-performance Rust library for Git internal objects, Pack files, and AI-assisted development objects (Intent, Plan, Task, Run, Evidence, Decision) with delta compression, streaming I/O, and smart protocol support.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
//! Minimal Git index (.git/index) reader/writer that maps working tree metadata to `IndexEntry`
//! records, including POSIX timestamp handling and hash serialization helpers.

#[cfg(unix)]
use std::os::unix::fs::MetadataExt;
#[cfg(unix)]
use std::time::Duration;
use std::{
    collections::BTreeMap,
    fmt::{Display, Formatter},
    fs::{self, File},
    io,
    io::{BufReader, Read, Write},
    path::{Path, PathBuf},
    time::{SystemTime, UNIX_EPOCH},
};

use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt};

use crate::{
    errors::GitError,
    hash::{ObjectHash, get_hash_kind},
    internal::pack::wrapper::Wrapper,
    utils::{self, HashAlgorithm},
};

/// POSIX time with seconds and nanoseconds
#[derive(PartialEq, Eq, Debug, Clone)]
pub struct Time {
    seconds: u32,
    nanos: u32,
}
impl Time {
    /// Read Time from stream
    pub fn from_stream(stream: &mut impl Read) -> Result<Self, GitError> {
        let seconds = stream.read_u32::<BigEndian>()?;
        let nanos = stream.read_u32::<BigEndian>()?;
        Ok(Time { seconds, nanos })
    }

    /// Convert to SystemTime
    #[allow(dead_code)]
    fn to_system_time(&self) -> SystemTime {
        UNIX_EPOCH + std::time::Duration::new(self.seconds.into(), self.nanos)
    }

    /// Create Time from SystemTime
    pub fn from_system_time(system_time: SystemTime) -> Self {
        match system_time.duration_since(UNIX_EPOCH) {
            Ok(duration) => {
                let seconds = duration
                    .as_secs()
                    .try_into()
                    .expect("Time is too far in the future");
                let nanos = duration.subsec_nanos();
                Time { seconds, nanos }
            }
            Err(_) => panic!("Time is before the UNIX epoch"),
        }
    }
}
impl Display for Time {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}:{}", self.seconds, self.nanos)
    }
}

#[cfg(unix)]
fn index_ctime(meta: &fs::Metadata) -> SystemTime {
    unix_metadata_time(meta.ctime(), meta.ctime_nsec())
}

#[cfg(not(unix))]
fn index_ctime(meta: &fs::Metadata) -> SystemTime {
    meta.created()
        .or_else(|_| meta.modified())
        .unwrap_or(UNIX_EPOCH)
}

#[cfg(unix)]
fn index_mtime(meta: &fs::Metadata) -> SystemTime {
    unix_metadata_time(meta.mtime(), meta.mtime_nsec())
}

#[cfg(not(unix))]
fn index_mtime(meta: &fs::Metadata) -> SystemTime {
    meta.modified()
        .or_else(|_| meta.created())
        .unwrap_or(UNIX_EPOCH)
}

#[cfg(unix)]
fn unix_metadata_time(seconds: i64, nanos: i64) -> SystemTime {
    if seconds < 0 {
        return UNIX_EPOCH;
    }

    let nanos = u32::try_from(nanos)
        .ok()
        .filter(|nanos| *nanos < 1_000_000_000)
        .unwrap_or(0);

    UNIX_EPOCH + Duration::new(seconds as u64, nanos)
}

/// 16 bits
#[derive(Debug)]
pub struct Flags {
    pub assume_valid: bool,
    pub extended: bool,   // must be 0 in v2
    pub stage: u8,        // 2-bit during merge
    pub name_length: u16, // 12-bit
}

impl From<u16> for Flags {
    fn from(flags: u16) -> Self {
        Flags {
            assume_valid: flags & 0x8000 != 0,
            extended: flags & 0x4000 != 0,
            stage: ((flags & 0x3000) >> 12) as u8,
            name_length: flags & 0xFFF,
        }
    }
}

impl TryInto<u16> for &Flags {
    type Error = &'static str;
    fn try_into(self) -> Result<u16, Self::Error> {
        let mut flags = 0u16;
        if self.assume_valid {
            flags |= 0x8000; // 16
        }
        if self.extended {
            flags |= 0x4000; // 15
        }
        flags |= (self.stage as u16) << 12; // 13-14
        if self.name_length > 0xFFF {
            return Err("Name length is too long");
        }
        flags |= self.name_length; // 0-11
        Ok(flags)
    }
}

impl Flags {
    pub fn new(name_len: u16) -> Self {
        Flags {
            assume_valid: true,
            extended: false,
            stage: 0,
            name_length: name_len,
        }
    }
}

/// An entry in the Git index file.
pub struct IndexEntry {
    pub ctime: Time,
    pub mtime: Time,
    pub dev: u32,  // 0 for windows
    pub ino: u32,  // 0 for windows
    pub mode: u32, // 0o100644 // 4-bit object type + 3-bit unused + 9-bit unix permission
    pub uid: u32,  // 0 for windows
    pub gid: u32,  // 0 for windows
    pub size: u32,
    pub hash: ObjectHash,
    pub flags: Flags,
    pub name: String,
}
impl Display for IndexEntry {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "IndexEntry {{ ctime: {}, mtime: {}, dev: {}, ino: {}, mode: {:o}, uid: {}, gid: {}, size: {}, hash: {}, flags: {:?}, name: {} }}",
            self.ctime,
            self.mtime,
            self.dev,
            self.ino,
            self.mode,
            self.uid,
            self.gid,
            self.size,
            self.hash,
            self.flags,
            self.name
        )
    }
}

impl IndexEntry {
    /** Metadata must be got by [fs::symlink_metadata] to avoid following symlink */
    pub fn new(meta: &fs::Metadata, hash: ObjectHash, name: String) -> Self {
        let mut entry = IndexEntry {
            ctime: Time::from_system_time(index_ctime(meta)),
            mtime: Time::from_system_time(index_mtime(meta)),
            dev: 0,
            ino: 0,
            uid: 0,
            gid: 0,
            size: meta.len() as u32,
            hash,
            flags: Flags::new(name.len() as u16),
            name,
            mode: 0o100644,
        };
        #[cfg(unix)]
        {
            entry.dev = meta.dev() as u32;
            entry.ino = meta.ino() as u32;
            entry.uid = meta.uid();
            entry.gid = meta.gid();

            entry.mode = match meta.mode() & 0o170000/* file mode */ {
                0o100000 => {
                    match meta.mode() & 0o111 {
                        0 => 0o100644, // no execute permission
                        _ => 0o100755, // with execute permission
                    }
                }
                0o120000 => 0o120000, // symlink
                _ =>  entry.mode, // keep the original mode
            }
        }
        #[cfg(windows)]
        {
            if meta.is_symlink() {
                entry.mode = 0o120000;
            }
        }
        entry
    }

    /// - `file`: **to workdir path**
    /// - `workdir`: absolute or relative path
    pub fn new_from_file(file: &Path, hash: ObjectHash, workdir: &Path) -> io::Result<Self> {
        let name = file.to_str().unwrap().to_string();
        let file_abs = workdir.join(file);
        let meta = fs::symlink_metadata(file_abs)?; // without following symlink
        let index = IndexEntry::new(&meta, hash, name);
        Ok(index)
    }

    /// Create IndexEntry from blob object
    pub fn new_from_blob(name: String, hash: ObjectHash, size: u32) -> Self {
        IndexEntry {
            ctime: Time {
                seconds: 0,
                nanos: 0,
            },
            mtime: Time {
                seconds: 0,
                nanos: 0,
            },
            dev: 0,
            ino: 0,
            mode: 0o100644,
            uid: 0,
            gid: 0,
            size,
            hash,
            flags: Flags::new(name.len() as u16),
            name,
        }
    }
}

/// see [index-format](https://git-scm.com/docs/index-format)
/// <br> to Working Dir relative path
pub struct Index {
    entries: BTreeMap<(String, u8), IndexEntry>,
}

impl Index {
    pub fn new() -> Self {
        Index {
            entries: BTreeMap::new(),
        }
    }

    fn check_header(file: &mut impl Read) -> Result<u32, GitError> {
        let mut magic = [0; 4];
        file.read_exact(&mut magic)?;
        if magic != *b"DIRC" {
            return Err(GitError::InvalidIndexHeader(
                String::from_utf8_lossy(&magic).to_string(),
            ));
        }

        let version = file.read_u32::<BigEndian>()?;
        // only support v2 now
        if version != 2 {
            return Err(GitError::InvalidIndexHeader(version.to_string()));
        }

        let entries = file.read_u32::<BigEndian>()?;
        Ok(entries)
    }

    pub fn size(&self) -> usize {
        self.entries.len()
    }

    pub fn from_file(path: impl AsRef<Path>) -> Result<Self, GitError> {
        let file = File::open(path.as_ref())?; // read-only
        let total_size = file.metadata()?.len();
        let file = &mut Wrapper::new(BufReader::new(file)); // TODO move Wrapper & utils to a common module

        let num = Index::check_header(file)?;
        let mut index = Index::new();

        for _ in 0..num {
            let mut entry = IndexEntry {
                ctime: Time::from_stream(file)?,
                mtime: Time::from_stream(file)?,
                dev: file.read_u32::<BigEndian>()?, //utils::read_u32_be(file)?,
                ino: file.read_u32::<BigEndian>()?,
                mode: file.read_u32::<BigEndian>()?,
                uid: file.read_u32::<BigEndian>()?,
                gid: file.read_u32::<BigEndian>()?,
                size: file.read_u32::<BigEndian>()?,
                hash: utils::read_sha(file)?,
                flags: Flags::from(file.read_u16::<BigEndian>()?),
                name: String::new(),
            };
            let name_len = entry.flags.name_length as usize;
            let mut name = vec![0; name_len];
            file.read_exact(&mut name)?;
            // The exact encoding is undefined, but the '.' and '/' characters are encoded in 7-bit ASCII
            entry.name =
                String::from_utf8(name).map_err(|e| GitError::ConversionError(e.to_string()))?; // TODO check the encoding
            index
                .entries
                .insert((entry.name.clone(), entry.flags.stage), entry);

            // 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes
            // while keeping the name NUL-terminated.
            let hash_len = get_hash_kind().size();
            let entry_len = hash_len + 2 + name_len;
            let padding = 1 + ((8 - ((entry_len + 1) % 8)) % 8); // at least 1 byte nul
            utils::read_bytes(file, padding)?;
        }

        // Extensions
        while file.bytes_read() + get_hash_kind().size() < total_size as usize {
            // The remaining bytes must be the pack checksum (size = get_hash_kind().size())
            let sign = utils::read_bytes(file, 4)?;
            println!(
                "{:?}",
                String::from_utf8(sign.clone())
                    .map_err(|e| GitError::ConversionError(e.to_string()))?
            );
            // If the first byte is 'A'...'Z' the extension is optional and can be ignored.
            if sign[0] >= b'A' && sign[0] <= b'Z' {
                // Optional extension
                let size = file.read_u32::<BigEndian>()?;
                utils::read_bytes(file, size as usize)?; // Ignore the extension
            } else {
                // 'link' or 'sdir' extension
                return Err(GitError::InvalidIndexFile(
                    "Unsupported extension".to_string(),
                ));
            }
        }

        // check sum
        let file_hash = file.final_hash();
        let check_sum = utils::read_sha(file)?;
        if file_hash != check_sum {
            return Err(GitError::InvalidIndexFile("Check sum failed".to_string()));
        }
        assert_eq!(index.size(), num as usize);
        Ok(index)
    }

    pub fn to_file(&self, path: impl AsRef<Path>) -> Result<(), GitError> {
        let mut file = File::create(path)?;
        let mut hash = HashAlgorithm::new();

        let mut header = Vec::new();
        header.write_all(b"DIRC")?;
        header.write_u32::<BigEndian>(2u32)?; // version 2
        header.write_u32::<BigEndian>(self.entries.len() as u32)?;
        file.write_all(&header)?;
        hash.update(&header);

        for entry in self.entries.values() {
            let mut entry_bytes = Vec::new();
            entry_bytes.write_u32::<BigEndian>(entry.ctime.seconds)?;
            entry_bytes.write_u32::<BigEndian>(entry.ctime.nanos)?;
            entry_bytes.write_u32::<BigEndian>(entry.mtime.seconds)?;
            entry_bytes.write_u32::<BigEndian>(entry.mtime.nanos)?;
            entry_bytes.write_u32::<BigEndian>(entry.dev)?;
            entry_bytes.write_u32::<BigEndian>(entry.ino)?;
            entry_bytes.write_u32::<BigEndian>(entry.mode)?;
            entry_bytes.write_u32::<BigEndian>(entry.uid)?;
            entry_bytes.write_u32::<BigEndian>(entry.gid)?;
            entry_bytes.write_u32::<BigEndian>(entry.size)?;
            entry_bytes.write_all(entry.hash.as_ref())?;
            entry_bytes.write_u16::<BigEndian>((&entry.flags).try_into().unwrap())?;
            entry_bytes.write_all(entry.name.as_bytes())?;
            let hash_len = get_hash_kind().size();
            let entry_len = hash_len + 2 + entry.name.len();
            let padding = 1 + ((8 - ((entry_len + 1) % 8)) % 8); // at least 1 byte nul
            entry_bytes.write_all(&vec![0; padding])?;
            file.write_all(&entry_bytes)?;
            hash.update(&entry_bytes);
        }

        // Extensions

        // check sum
        let file_hash =
            ObjectHash::from_bytes(&hash.finalize()).map_err(GitError::InvalidIndexFile)?;
        file.write_all(file_hash.as_ref())?;
        Ok(())
    }

    pub fn refresh(&mut self, file: impl AsRef<Path>, workdir: &Path) -> Result<bool, GitError> {
        let path = file.as_ref();
        let name = path
            .to_str()
            .ok_or(GitError::InvalidPathError(format!("{path:?}")))?;

        if let Some(entry) = self.entries.get_mut(&(name.to_string(), 0)) {
            let abs_path = workdir.join(path);
            let meta = fs::symlink_metadata(&abs_path)?;
            let new_ctime = Time::from_system_time(index_ctime(&meta));
            let new_mtime = Time::from_system_time(index_mtime(&meta));
            let new_size = meta.len() as u32;

            // re-calculate SHA1/SHA256
            let mut file = File::open(&abs_path)?;
            let mut hasher = HashAlgorithm::new();
            io::copy(&mut file, &mut hasher)?;
            let new_hash = ObjectHash::from_bytes(&hasher.finalize()).unwrap();

            // refresh index
            if entry.ctime != new_ctime
                || entry.mtime != new_mtime
                || entry.size != new_size
                || entry.hash != new_hash
            {
                entry.ctime = new_ctime;
                entry.mtime = new_mtime;
                entry.size = new_size;
                entry.hash = new_hash;
                return Ok(true);
            }
        }
        Ok(false)
    }
}

impl Default for Index {
    fn default() -> Self {
        Self::new()
    }
}

impl Index {
    /// Load index. If it does not exist, return an empty index.
    pub fn load(index_file: impl AsRef<Path>) -> Result<Self, GitError> {
        let path = index_file.as_ref();
        if !path.exists() {
            return Ok(Index::new());
        }
        Index::from_file(path)
    }

    pub fn update(&mut self, entry: IndexEntry) {
        self.add(entry)
    }

    pub fn add(&mut self, entry: IndexEntry) {
        self.entries
            .insert((entry.name.clone(), entry.flags.stage), entry);
    }

    pub fn remove(&mut self, name: &str, stage: u8) -> Option<IndexEntry> {
        self.entries.remove(&(name.to_string(), stage))
    }

    pub fn get(&self, name: &str, stage: u8) -> Option<&IndexEntry> {
        self.entries.get(&(name.to_string(), stage))
    }

    pub fn tracked(&self, name: &str, stage: u8) -> bool {
        self.entries.contains_key(&(name.to_string(), stage))
    }

    pub fn get_hash(&self, file: &str, stage: u8) -> Option<ObjectHash> {
        self.get(file, stage).map(|entry| entry.hash)
    }

    pub fn verify_hash(&self, file: &str, stage: u8, hash: &ObjectHash) -> bool {
        let inner_hash = self.get_hash(file, stage);
        if let Some(inner_hash) = inner_hash {
            &inner_hash == hash
        } else {
            false
        }
    }
    /// is file modified after last `add` (need hash to confirm content change)
    /// - `workdir` is used to rebuild absolute file path
    pub fn is_modified(&self, file: &str, stage: u8, workdir: &Path) -> bool {
        if let Some(entry) = self.get(file, stage) {
            let path_abs = workdir.join(file);
            let meta = path_abs.symlink_metadata().unwrap();
            // TODO more fields
            let same = entry.ctime == Time::from_system_time(index_ctime(&meta))
                && entry.mtime == Time::from_system_time(index_mtime(&meta))
                && entry.size == meta.len() as u32;

            !same
        } else {
            panic!("File not found in index");
        }
    }

    /// Get all entries with the same stage
    pub fn tracked_entries(&self, stage: u8) -> Vec<&IndexEntry> {
        // ? should use stage or not
        self.entries
            .iter()
            .filter(|(_, entry)| entry.flags.stage == stage)
            .map(|(_, entry)| entry)
            .collect()
    }

    /// Get all tracked files(stage = 0)
    pub fn tracked_files(&self) -> Vec<PathBuf> {
        self.tracked_entries(0)
            .iter()
            .map(|entry| PathBuf::from(&entry.name))
            .collect()
    }

    /// Judge if the file(s) of `dir` is in the index
    /// - false if `dir` is a file
    pub fn contains_dir_file(&self, dir: &str) -> bool {
        let dir = Path::new(dir);
        self.entries.iter().any(|((name, _), _)| {
            let path = Path::new(name);
            path.starts_with(dir) && path != dir // TODO change to is_sub_path!
        })
    }

    /// remove all files in `dir` from index
    /// - do nothing if `dir` is a file
    pub fn remove_dir_files(&mut self, dir: &str) -> Vec<String> {
        let dir = Path::new(dir);
        let mut removed = Vec::new();
        self.entries.retain(|(name, _), _| {
            let path = Path::new(name);
            if path.starts_with(dir) && path != dir {
                removed.push(name.clone());
                false
            } else {
                true
            }
        });
        removed
    }

    /// saved to index file
    pub fn save(&self, index_file: impl AsRef<Path>) -> Result<(), GitError> {
        self.to_file(index_file)
    }
}

#[cfg(test)]
mod tests {
    use std::io::Cursor;

    use super::*;
    use crate::hash::{HashKind, set_hash_kind_for_test};

    /// Test Time conversion
    #[test]
    fn test_time() {
        let time = Time {
            seconds: 0,
            nanos: 0,
        };
        let system_time = time.to_system_time();
        let new_time = Time::from_system_time(system_time);
        assert_eq!(time, new_time);
    }

    /// Test Flags conversion
    #[test]
    fn test_check_header() {
        let mut source = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        source.push("tests/data/index/index-2");

        let file = File::open(source).unwrap();
        let entries = Index::check_header(&mut BufReader::new(file)).unwrap();
        assert_eq!(entries, 2);
    }

    /// Test IndexEntry creation
    #[test]
    fn test_index() {
        let _guard = set_hash_kind_for_test(HashKind::Sha1);
        let mut source = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        source.push("tests/data/index/index-760");

        let index = Index::from_file(source).unwrap();
        assert_eq!(index.size(), 760);
        for entry in index.entries.values() {
            println!("{entry}");
        }
    }

    /// Test IndexEntry creation with SHA256
    #[test]
    fn test_index_sha256() {
        let _guard = set_hash_kind_for_test(HashKind::Sha256);
        let mut source = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        source.push("tests/data/index/index-9-256");

        let index = Index::from_file(source).unwrap();
        assert_eq!(index.size(), 9);
        for entry in index.entries.values() {
            println!("{entry}");
        }
    }

    /// Flags bit packing/unpacking covers all fields and enforces name length limit.
    #[test]
    fn flags_round_trip_and_length_limit() {
        let mut flags = Flags {
            assume_valid: true,
            extended: true,
            stage: 2,
            name_length: 0x0ABC,
        };
        let packed: u16 = (&flags).try_into().expect("should pack");
        let unpacked = Flags::from(packed);
        assert_eq!(unpacked.assume_valid, flags.assume_valid);
        assert_eq!(unpacked.extended, flags.extended);
        assert_eq!(unpacked.stage, flags.stage);
        assert_eq!(unpacked.name_length, flags.name_length);

        flags.name_length = 0x1FFF;
        let overflow: Result<u16, _> = (&flags).try_into();
        assert!(overflow.is_err(), "length overflow should err");
    }

    /// IndexEntry::new_from_blob populates fields and sets flags length.
    #[test]
    fn index_entry_new_from_blob_populates_fields() {
        let hash = ObjectHash::from_bytes(&[0u8; 20]).unwrap();
        let entry = IndexEntry::new_from_blob("file.txt".to_string(), hash, 42);
        assert_eq!(entry.name, "file.txt");
        assert_eq!(entry.size, 42);
        assert_eq!(entry.hash, hash);
        assert_eq!(entry.flags.name_length, "file.txt".len() as u16);
        assert_eq!(entry.mode, 0o100644);
    }

    /// Index container operations: add/get/tracked/dir helpers.
    #[test]
    fn index_add_and_query_helpers() {
        let _guard = set_hash_kind_for_test(HashKind::Sha1);
        let mut index = Index::new();
        let hash = ObjectHash::from_bytes(&[1u8; 20]).unwrap();
        let entry = IndexEntry::new_from_blob("a/b.txt".to_string(), hash, 10);
        index.add(entry);

        // get finds stage-0 by name
        let got = index.get("a/b.txt", 0).expect("entry exists");
        assert_eq!(got.hash, hash);

        // tracked_entries/files return stage-0 paths
        let tracked = index.tracked_entries(0);
        assert_eq!(tracked.len(), 1);
        let files = index.tracked_files();
        assert_eq!(files, vec![PathBuf::from("a/b.txt")]);

        // contains_dir_file true for subpath, false for exact file
        assert!(index.contains_dir_file("a"));
        assert!(!index.contains_dir_file("a/b.txt"));

        // remove_dir_files removes under dir and returns removed names
        let removed = index.remove_dir_files("a");
        assert_eq!(removed, vec!["a/b.txt".to_string()]);
        assert!(index.get("a/b.txt", 0).is_none());
    }

    /// check_header should reject bad magic/versions and accept valid header.
    #[test]
    fn check_header_validation() {
        // valid header: "DIRC" + version 2 + 0 entries
        let mut valid = Cursor::new(b"DIRC\0\0\0\x02\0\0\0\0".to_vec());
        let entries = Index::check_header(&mut valid).expect("valid header");
        assert_eq!(entries, 0);

        // bad magic
        let mut bad_magic = Cursor::new(b"XXXX\0\0\0\x02\0\0\0\0".to_vec());
        assert!(Index::check_header(&mut bad_magic).is_err());

        // bad version
        let mut bad_version = Cursor::new(b"DIRC\0\0\0\x01\0\0\0\0".to_vec());
        assert!(Index::check_header(&mut bad_version).is_err());
    }

    /// Test saving Index to file
    #[test]
    fn test_index_to_file() {
        let temp_dir = tempfile::tempdir().unwrap();
        let temp_path = temp_dir.path().join("index-760");

        let mut source = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        source.push("tests/data/index/index-760");

        let index = Index::from_file(source).unwrap();
        index.to_file(&temp_path).unwrap();
        let new_index = Index::from_file(temp_path).unwrap();
        assert_eq!(index.size(), new_index.size());
    }

    /// Test IndexEntry creation from file
    #[test]
    fn test_index_entry_create() {
        let _guard = set_hash_kind_for_test(HashKind::Sha1);
        let mut source = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        source.push("Cargo.toml");

        let file = Path::new(source.as_path()); // use as a normal file
        let hash = ObjectHash::from_bytes(&[0; 20]).unwrap();
        let workdir = Path::new("../");
        let entry = IndexEntry::new_from_file(file, hash, workdir).unwrap();
        println!("{entry}");
    }

    /// Test IndexEntry creation from file with SHA256
    #[test]
    fn test_index_entry_create_sha256() {
        let _guard = set_hash_kind_for_test(HashKind::Sha256);
        let mut source = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        source.push("Cargo.toml");

        let file = Path::new(source.as_path());
        let hash = ObjectHash::from_bytes(&[0u8; 32]).unwrap();
        let workdir = Path::new("../");
        let entry = IndexEntry::new_from_file(file, hash, workdir).unwrap();
        println!("{entry}");
    }
}