Struct git_index::File

source · 
pub struct File { /* private fields */ }
Expand description

An index file whose state was read from a file on disk.

Implementations§

Consumption

Take the state and discard the rest.

Take all non-copy parts of the index.

Access

The path from which the index was read or to which it is supposed to be written when used with File::from_state().

The checksum over the file that was read or written to disk, or None if the state in memory was never serialized.

Note that even if Some, it will only represent the state in memory right after reading or writing.

Initialization

Open an index file at path with options, assuming object_hash is used throughout the file.

Consume state and pretend it was read from path, setting our checksum to null.

File instances created like that should be written to disk to set the correct checksum via [File::write()].

Verify the integrity of the index to assure its consistency.

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.

Examples found in repository?
src/file/write.rs (line 42)
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

    pub fn write(&mut self, options: write::Options) -> Result<(), Error> {
        let mut lock = std::io::BufWriter::new(git_lock::File::acquire_to_update_resource(
            &self.path,
            git_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(err.into_error().into()),
        };
        self.state.version = version;
        self.checksum = Some(digest);
        Ok(())
    }

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.

Methods from Deref<Target = State>§

Return the version used to store this state’s information on disk.

Return the kind of hashes used in this instance.

Return our entries

Examples found in repository?
src/write.rs (line 67)
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

    pub fn write_to(&self, out: impl std::io::Write, Options { extensions }: Options) -> std::io::Result<Version> {
        let version = self.detect_required_version();

        let mut write = CountBytes::new(out);
        let num_entries = self
            .entries()
            .len()
            .try_into()
            .expect("definitely not 4billion entries");

        let offset_to_entries = header(&mut write, version, num_entries)?;
        let offset_to_extensions = entries(&mut write, self, offset_to_entries)?;
        let (extension_toc, out) = self.write_extensions(write, offset_to_extensions, extensions)?;

        if num_entries > 0
            && extensions
                .should_write(extension::end_of_index_entry::SIGNATURE)
                .is_some()
            && !extension_toc.is_empty()
        {
            extension::end_of_index_entry::write_to(out, self.object_hash, offset_to_extensions, extension_toc)?
        }

        Ok(version)
    }

    fn write_extensions<T>(
        &self,
        mut write: CountBytes<T>,
        offset_to_extensions: u32,
        extensions: Extensions,
    ) -> std::io::Result<(Vec<(extension::Signature, u32)>, T)>
    where
        T: std::io::Write,
    {
        type WriteExtFn<'a> = &'a dyn Fn(&mut dyn std::io::Write) -> Option<std::io::Result<extension::Signature>>;
        let extensions: &[WriteExtFn<'_>] = &[
            &|write| {
                extensions
                    .should_write(extension::tree::SIGNATURE)
                    .and_then(|signature| self.tree().map(|tree| tree.write_to(write).map(|_| signature)))
            },
            &|write| {
                self.is_sparse()
                    .then(|| extension::sparse::write_to(write).map(|_| extension::sparse::SIGNATURE))
            },
        ];

        let mut offset_to_previous_ext = offset_to_extensions;
        let mut out = Vec::with_capacity(5);
        for write_ext in extensions {
            if let Some(signature) = write_ext(&mut write).transpose()? {
                let offset_past_ext = write.count;
                let ext_size = offset_past_ext - offset_to_previous_ext - (extension::MIN_SIZE as u32);
                offset_to_previous_ext = offset_past_ext;
                out.push((signature, ext_size));
            }
        }
        Ok((out, write.inner))
    }
}

impl State {
    fn detect_required_version(&self) -> Version {
        self.entries
            .iter()
            .find_map(|e| e.flags.contains(entry::Flags::EXTENDED).then(|| Version::V3))
            .unwrap_or(Version::V2)
    }
}

fn header<T: std::io::Write>(
    out: &mut CountBytes<T>,
    version: Version,
    num_entries: u32,
) -> Result<u32, std::io::Error> {
    let version = match version {
        Version::V2 => 2_u32.to_be_bytes(),
        Version::V3 => 3_u32.to_be_bytes(),
        Version::V4 => 4_u32.to_be_bytes(),
    };

    out.write_all(crate::decode::header::SIGNATURE)?;
    out.write_all(&version)?;
    out.write_all(&num_entries.to_be_bytes())?;

    Ok(out.count)
}

fn entries<T: std::io::Write>(out: &mut CountBytes<T>, state: &State, header_size: u32) -> Result<u32, std::io::Error> {
    for entry in state.entries() {
        entry.write_to(&mut *out, state)?;
        match (out.count - header_size) % 8 {
            0 => {}
            n => {
                let eight_null_bytes = [0u8; 8];
                out.write_all(&eight_null_bytes[n as usize..])?;
            }
        };
    }

    Ok(out.count)
}

Return our path backing, the place which keeps all paths one after another, with entries storing only the range to access them.

Sometimes it’s needed to remove the path backing to allow certain mutation to happen in the state while supporting reading the entry’s path.

After usage of the storage obtained by take_path_backing(), return it here. Note that it must not be empty.

Runs filter_map on all entries, returning an iterator over all paths along with the result of filter_map.

Return mutable entries in a slice.

Return mutable entries along with their paths in an iterator.

Return mutable entries along with their path, as obtained from backing.

Find the entry index in entries() matching the given repository-relative path and stage, or None.

Use the index for accessing multiple stages if they exists, but at least the single matching entry.

Examples found in repository?
src/access/mod.rs (line 97)
96
97
98
99

    pub fn entry_by_path_and_stage(&self, path: &BStr, stage: entry::Stage) -> Option<&Entry> {
        self.entry_index_by_path_and_stage(path, stage)
            .map(|idx| &self.entries[idx])
    }

Like entry_index_by_path_and_stage(), but returns the entry instead of the index.

Return the entry at idx or panic if the index is out of bounds.

The idx is typically returned by entry_by_path_and_stage().

Returns a boolean value indicating whether the index is sparse or not.

An index is sparse if it contains at least one Mode::DIR entry.

Examples found in repository?
src/write.rs (line 105)
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

    fn write_extensions<T>(
        &self,
        mut write: CountBytes<T>,
        offset_to_extensions: u32,
        extensions: Extensions,
    ) -> std::io::Result<(Vec<(extension::Signature, u32)>, T)>
    where
        T: std::io::Write,
    {
        type WriteExtFn<'a> = &'a dyn Fn(&mut dyn std::io::Write) -> Option<std::io::Result<extension::Signature>>;
        let extensions: &[WriteExtFn<'_>] = &[
            &|write| {
                extensions
                    .should_write(extension::tree::SIGNATURE)
                    .and_then(|signature| self.tree().map(|tree| tree.write_to(write).map(|_| signature)))
            },
            &|write| {
                self.is_sparse()
                    .then(|| extension::sparse::write_to(write).map(|_| extension::sparse::SIGNATURE))
            },
        ];

        let mut offset_to_previous_ext = offset_to_extensions;
        let mut out = Vec::with_capacity(5);
        for write_ext in extensions {
            if let Some(signature) = write_ext(&mut write).transpose()? {
                let offset_past_ext = write.count;
                let ext_size = offset_past_ext - offset_to_previous_ext - (extension::MIN_SIZE as u32);
                offset_to_previous_ext = offset_past_ext;
                out.push((signature, ext_size));
            }
        }
        Ok((out, write.inner))
    }

Access the tree extension.

Examples found in repository?
src/verify.rs (line 68)
64
65
66
67
68
69
70
71
72

    pub fn verify_extensions<F>(&self, use_find: bool, find: F) -> Result<(), extensions::Error>
    where
        F: for<'a> FnMut(&git_hash::oid, &'a mut Vec<u8>) -> Option<git_object::TreeRefIter<'a>>,
    {
        self.tree().map(|t| t.verify(use_find, find)).transpose()?;
        // TODO: verify links by running the whole set of tests on the index
        //       - do that once we load it as well, or maybe that's lazy loaded? Too many questions for now.
        Ok(())
    }
More examples
Hide additional examples
src/write.rs (line 102)
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

    fn write_extensions<T>(
        &self,
        mut write: CountBytes<T>,
        offset_to_extensions: u32,
        extensions: Extensions,
    ) -> std::io::Result<(Vec<(extension::Signature, u32)>, T)>
    where
        T: std::io::Write,
    {
        type WriteExtFn<'a> = &'a dyn Fn(&mut dyn std::io::Write) -> Option<std::io::Result<extension::Signature>>;
        let extensions: &[WriteExtFn<'_>] = &[
            &|write| {
                extensions
                    .should_write(extension::tree::SIGNATURE)
                    .and_then(|signature| self.tree().map(|tree| tree.write_to(write).map(|_| signature)))
            },
            &|write| {
                self.is_sparse()
                    .then(|| extension::sparse::write_to(write).map(|_| extension::sparse::SIGNATURE))
            },
        ];

        let mut offset_to_previous_ext = offset_to_extensions;
        let mut out = Vec::with_capacity(5);
        for write_ext in extensions {
            if let Some(signature) = write_ext(&mut write).transpose()? {
                let offset_past_ext = write.count;
                let ext_size = offset_past_ext - offset_to_previous_ext - (extension::MIN_SIZE as u32);
                offset_to_previous_ext = offset_past_ext;
                out.push((signature, ext_size));
            }
        }
        Ok((out, write.inner))
    }

Access the link extension.

Obtain the resolve-undo extension.

Obtain the untracked extension.

Obtain the fsmonitor extension.

Assure our entries are consistent.

Note: find cannot be Option<F> as we can’t call it with a closure then due to the indirection through Some.

Serialize this instance to out with options.

Examples found in repository?
src/file/write.rs (line 26)
20
21
22
23
24
25
26
27
28
29
30
31

    pub fn write_to(
        &self,
        mut out: impl std::io::Write,
        options: write::Options,
    ) -> std::io::Result<(Version, git_hash::ObjectId)> {
        let mut hasher = hash::Write::new(&mut out, self.state.object_hash);
        let version = self.state.write_to(&mut hasher, options)?;

        let hash = hasher.hash.digest();
        out.write_all(&hash)?;
        Ok((version, git_hash::ObjectId::from(hash)))
    }

Trait Implementations§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
The resulting type after dereferencing.
Dereferences the value.
Mutably dereferences the value.

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.