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
use crate::{File, Version, write};
/// The error produced by [`File::write()`].
#[derive(Debug, thiserror::Error)]
#[expect(missing_docs)]
pub enum Error {
#[error(transparent)]
Io(#[from] gix_hash::io::Error),
#[error("Could not acquire lock for index file")]
AcquireLock(#[from] gix_lock::acquire::Error),
#[error("Could not commit lock for index file")]
CommitLock(#[from] gix_lock::commit::Error<gix_lock::File>),
}
impl File {
/// Write the index to `out` with `options`, to be readable by [`File::at()`], returning the version that was actually written
/// to retain all information of this index.
///
/// Note that the `tree` (tree-cache) extension is written as-is and is **not** recomputed or
/// invalidated to match the current entries; see [`File::write()`] for the implications and the
/// recommended workaround.
pub fn write_to(
&self,
mut out: impl std::io::Write,
options: write::Options,
) -> Result<(Version, gix_hash::ObjectId), gix_hash::io::Error> {
let _span = gix_features::trace::detail!("gix_index::File::write_to()", skip_hash = options.skip_hash);
let (version, hash) = if options.skip_hash {
let out: &mut dyn std::io::Write = &mut out;
let version = self.state.write_to(out, options)?;
(version, self.state.object_hash.null())
} else {
let mut hasher = gix_hash::io::Write::new(&mut out, self.state.object_hash);
let out: &mut dyn std::io::Write = &mut hasher;
let version = self.state.write_to(out, options)?;
(version, hasher.hash.try_finalize()?)
};
out.write_all(hash.as_slice())?;
Ok((version, hash))
}
/// Write ourselves to the path we were read from after acquiring a lock, using `options`.
///
/// Note that the hash produced will be stored which is why we need to be mutable.
///
/// ### The `tree` (tree-cache) extension is written as-is
///
/// The `tree` extension (tree-cache) is serialized from its current in-memory state; it is
/// **not** recomputed or invalidated to match the entries. So if entries were modified since the
/// index was read, the tree-cache is written back still marked valid even though it is now stale.
///
/// Git uses the tree-cache to skip unchanged directories when building a tree (on `git commit` /
/// `git write-tree`), so a stale-but-valid tree-cache can make a later commit capture outdated
/// subtree content; more generally, `git status` and later commits can disagree about what is
/// staged.
///
/// Until the tree-cache is updated on write (see [issue #2421]), remove it with
/// [`State::remove_tree()`](crate::State::remove_tree()) before writing whenever entries were
/// changed:
///
/// ```ignore
/// index.remove_tree();
/// index.write(gix_index::write::Options::default())?;
/// ```
///
/// [issue #2421]: https://github.com/GitoxideLabs/gitoxide/issues/2421
pub fn write(&mut self, options: write::Options) -> Result<(), Error> {
let _span = gix_features::trace::detail!("gix_index::File::write()", path = ?self.path);
let mut lock = std::io::BufWriter::with_capacity(
64 * 1024,
gix_lock::File::acquire_to_update_resource(&self.path, gix_lock::acquire::Fail::Immediately, None)?,
);
let (version, digest) = self.write_to(&mut lock, options)?;
match lock.into_inner() {
Ok(lock) => lock.commit()?,
Err(err) => return Err(Error::Io(err.into_error().into())),
};
self.state.version = version;
self.checksum = Some(digest);
Ok(())
}
}