Skip to main content

file_identify/
meta.rs

1//! File metadata relevant to identification: kind and executability.
2
3use std::fs;
4
5/// The kind of a file-system entry, as seen by `lstat` (symlinks are not
6/// followed).
7#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
8#[non_exhaustive]
9pub enum FileKind {
10    /// A regular file.
11    Regular,
12    /// A directory (also used for git submodules / gitlinks).
13    Directory,
14    /// A symbolic link.
15    ///
16    /// On Windows also a directory junction or another name-surrogate
17    /// reparse point, which the standard library reports as a symlink; see
18    /// [`FileKind::from_file_type`].
19    Symlink,
20    /// A Unix domain socket.
21    Socket,
22    /// Anything else: FIFO, character or block device, … identify treats
23    /// these as files and opens them (which can block forever on a FIFO);
24    /// this crate tags them `file` without ever opening them.
25    Other,
26}
27
28impl FileKind {
29    /// Classify a [`fs::FileType`] (from [`fs::symlink_metadata`]).
30    ///
31    /// On Windows, [`fs::FileType::is_symlink`] is true for every
32    /// name-surrogate reparse point, so a directory junction is
33    /// [`FileKind::Symlink`], while `os.lstat` in Python (and therefore
34    /// identify) reports a junction as a directory and only true symlinks as
35    /// links. The reparse tag that would tell them apart is not available
36    /// from the standard library without `unsafe` code.
37    #[must_use]
38    pub fn from_file_type(file_type: fs::FileType) -> Self {
39        if file_type.is_dir() {
40            Self::Directory
41        } else if file_type.is_symlink() {
42            Self::Symlink
43        } else if is_socket(file_type) {
44            Self::Socket
45        } else if file_type.is_file() {
46            Self::Regular
47        } else {
48            Self::Other
49        }
50    }
51}
52
53#[cfg(unix)]
54fn is_socket(file_type: fs::FileType) -> bool {
55    use std::os::unix::fs::FileTypeExt;
56    file_type.is_socket()
57}
58
59#[cfg(not(unix))]
60fn is_socket(_file_type: fs::FileType) -> bool {
61    false
62}
63
64/// How to decide whether a file is executable.
65#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
66#[non_exhaustive]
67pub enum ExecPolicy {
68    /// identify's `os.access(path, os.X_OK)`, so results match pre-commit:
69    ///
70    /// * Unix: `access(2)` semantics evaluated from the file's mode, owner
71    ///   and group against the process's real uid, gid and supplementary
72    ///   groups (queried once and cached): root needs any `x` bit, the owner
73    ///   the user bit, group members the group bit, others the other bit.
74    ///   ACLs and `noexec` mounts are not consulted.
75    /// * Windows: every file is executable (`os.access` ignores `X_OK`
76    ///   there), so every unknown-name file is checked for a shebang.
77    #[default]
78    PythonCompat,
79    /// git's notion of an executable file: the owner `x` bit
80    /// (`mode & 0o100 != 0`). This is the bit `git add` records as `100755`
81    /// (git's `ce_permissions`), so on Unix with `core.fileMode=true` the
82    /// result agrees with [`Meta::from_git_mode`] on the staged mode. Group
83    /// and other bits are ignored: `0o655` is not executable. Never
84    /// executable on non-Unix platforms.
85    ///
86    /// For lefthook's notion ("any `x` bit") build the [`Meta`] by hand:
87    /// `Meta::regular(mode & 0o111 != 0)`.
88    ModeBits,
89}
90
91impl ExecPolicy {
92    /// Whether a regular file with this metadata counts as executable.
93    #[must_use]
94    pub fn is_executable(self, metadata: &fs::Metadata) -> bool {
95        imp::is_executable(self, metadata)
96    }
97}
98
99#[cfg(unix)]
100mod imp {
101    use super::ExecPolicy;
102    use std::fs;
103    use std::os::unix::fs::MetadataExt;
104    use std::sync::OnceLock;
105
106    /// The process's real uid, gid and supplementary groups, queried lazily
107    /// (most files are owned by the current user, so the group list is
108    /// rarely needed) and cached for the life of the process.
109    fn uid() -> u32 {
110        static UID: OnceLock<u32> = OnceLock::new();
111        *UID.get_or_init(|| rustix::process::getuid().as_raw())
112    }
113
114    fn in_group(gid: u32) -> bool {
115        static GID: OnceLock<u32> = OnceLock::new();
116        static GROUPS: OnceLock<Box<[u32]>> = OnceLock::new();
117        *GID.get_or_init(|| rustix::process::getgid().as_raw()) == gid
118            || GROUPS
119                .get_or_init(|| {
120                    rustix::process::getgroups()
121                        .map(|groups| {
122                            groups
123                                .into_iter()
124                                .map(rustix::process::Gid::as_raw)
125                                .collect()
126                        })
127                        .unwrap_or_default()
128                })
129                .contains(&gid)
130    }
131
132    pub(super) fn is_executable(policy: ExecPolicy, md: &fs::Metadata) -> bool {
133        let mode = md.mode();
134        match policy {
135            ExecPolicy::ModeBits => mode & 0o100 != 0,
136            ExecPolicy::PythonCompat => {
137                let uid = uid();
138                if uid == 0 {
139                    mode & 0o111 != 0
140                } else if md.uid() == uid {
141                    mode & 0o100 != 0
142                } else if in_group(md.gid()) {
143                    mode & 0o010 != 0
144                } else {
145                    mode & 0o001 != 0
146                }
147            }
148        }
149    }
150}
151
152#[cfg(not(unix))]
153mod imp {
154    use super::ExecPolicy;
155    use std::fs;
156
157    pub(super) fn is_executable(policy: ExecPolicy, _md: &fs::Metadata) -> bool {
158        match policy {
159            ExecPolicy::PythonCompat => cfg!(windows),
160            ExecPolicy::ModeBits => false,
161        }
162    }
163}
164
165/// What identification needs to know about a path besides its name: its
166/// [`FileKind`] and whether it is executable.
167///
168/// Build it from [`fs::Metadata`] ([`Meta::from_metadata`]), from a git index
169/// mode without any system call ([`Meta::from_git_mode`]), or by hand.
170#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
171pub struct Meta {
172    kind: FileKind,
173    executable: bool,
174}
175
176impl Meta {
177    /// A meta with the given kind and executable flag.
178    #[must_use]
179    pub const fn new(kind: FileKind, executable: bool) -> Self {
180        Self { kind, executable }
181    }
182
183    /// A regular file.
184    #[must_use]
185    pub const fn regular(executable: bool) -> Self {
186        Self::new(FileKind::Regular, executable)
187    }
188
189    /// The entry kind.
190    #[must_use]
191    pub const fn kind(self) -> FileKind {
192        self.kind
193    }
194
195    /// Whether the entry is executable (only meaningful for regular files
196    /// and [`FileKind::Other`]).
197    #[must_use]
198    pub const fn is_executable(self) -> bool {
199        self.executable
200    }
201
202    /// The same meta with a different executable flag.
203    #[must_use]
204    pub const fn with_executable(self, executable: bool) -> Self {
205        Self::new(self.kind, executable)
206    }
207
208    /// From `lstat` metadata ([`fs::symlink_metadata`]); executability is
209    /// decided by `policy` for regular files and [`FileKind::Other`].
210    #[must_use]
211    pub fn from_metadata(metadata: &fs::Metadata, policy: ExecPolicy) -> Self {
212        let kind = FileKind::from_file_type(metadata.file_type());
213        let executable =
214            matches!(kind, FileKind::Regular | FileKind::Other) && policy.is_executable(metadata);
215        Self::new(kind, executable)
216    }
217
218    /// From a git index / tree mode, with git's own executable bit:
219    ///
220    /// | mode | meta |
221    /// |---|---|
222    /// | `100644` (any `100xxx` without the owner `x` bit) | regular file |
223    /// | `100755` (any `100xxx` with the owner `x` bit) | executable regular file |
224    /// | `120000` | symlink |
225    /// | `160000` (gitlink / submodule), `040000` (tree) | directory |
226    /// | anything else | `None` |
227    ///
228    /// This needs no system call. It matches what identify would see on a
229    /// checkout where the work tree agrees with the index (e.g. after
230    /// pre-commit stashed unstaged changes) on Unix with
231    /// `core.fileMode=true` and `core.symlinks=true`. On Windows identify
232    /// considers every file executable; use [`Meta::from_git_mode_with`]
233    /// with [`ExecPolicy::PythonCompat`] to reproduce that.
234    ///
235    /// # Symlinks: do not trust `120000` with `core.symlinks=false`
236    ///
237    /// `120000` says the *index* holds a symlink. With `core.symlinks=false`
238    /// (the usual configuration on Windows, and set automatically on file
239    /// systems without symlinks) git checks it out as a regular file that
240    /// contains the target path, which identify tags `file`, `text` and
241    /// `executable` on Windows. On Windows, or whenever `core.symlinks` is
242    /// false, `lstat` such entries instead ([`tags_from_path`] or
243    /// [`tags_from_metadata`]).
244    ///
245    /// [`tags_from_path`]: crate::tags_from_path
246    /// [`tags_from_metadata`]: crate::tags_from_metadata
247    ///
248    /// ```
249    /// use file_identify::{FileKind, Meta};
250    ///
251    /// assert_eq!(Meta::from_git_mode(0o100755), Some(Meta::regular(true)));
252    /// assert_eq!(Meta::from_git_mode(0o120000).map(Meta::kind), Some(FileKind::Symlink));
253    /// assert_eq!(Meta::from_git_mode(0), None);
254    /// ```
255    #[must_use]
256    pub const fn from_git_mode(mode: u32) -> Option<Self> {
257        match mode & 0o170_000 {
258            // git's canon_mode / ce_permissions: only the owner bit counts.
259            0o100_000 => Some(Self::regular(mode & 0o100 != 0)),
260            0o120_000 => Some(Self::new(FileKind::Symlink, false)),
261            0o160_000 | 0o040_000 => Some(Self::new(FileKind::Directory, false)),
262            _ => None,
263        }
264    }
265
266    /// Like [`Meta::from_git_mode`], with platform executable semantics:
267    /// [`ExecPolicy::PythonCompat`] on Windows marks every regular file
268    /// executable (as identify does); otherwise git's bit is used.
269    ///
270    /// A `120000` entry still gives [`FileKind::Symlink`]: on Windows a
271    /// checkout usually has a regular file there (`core.symlinks=false`), so
272    /// `lstat` those entries instead; see [`Meta::from_git_mode`].
273    #[must_use]
274    pub fn from_git_mode_with(mode: u32, policy: ExecPolicy) -> Option<Self> {
275        let meta = Self::from_git_mode(mode)?;
276        Some(match (policy, meta.kind) {
277            (ExecPolicy::PythonCompat, FileKind::Regular) if cfg!(windows) => {
278                meta.with_executable(true)
279            }
280            _ => meta,
281        })
282    }
283}
284
285#[cfg(test)]
286mod tests {
287    use super::*;
288
289    #[test]
290    fn git_modes() {
291        assert_eq!(Meta::from_git_mode(0o100_644), Some(Meta::regular(false)));
292        assert_eq!(Meta::from_git_mode(0o100_755), Some(Meta::regular(true)));
293        assert_eq!(Meta::from_git_mode(0o100_664), Some(Meta::regular(false)));
294        // Only the owner bit counts, as in git's ce_permissions (`git add`
295        // stages 0o655, 0o645 and 0o611 files as 100644).
296        assert_eq!(Meta::from_git_mode(0o100_655), Some(Meta::regular(false)));
297        assert_eq!(Meta::from_git_mode(0o100_611), Some(Meta::regular(false)));
298        assert_eq!(Meta::from_git_mode(0o100_700), Some(Meta::regular(true)));
299        assert_eq!(Meta::from_git_mode(0o100_100), Some(Meta::regular(true)));
300        assert_eq!(
301            Meta::from_git_mode(0o120_000),
302            Some(Meta::new(FileKind::Symlink, false))
303        );
304        assert_eq!(
305            Meta::from_git_mode(0o160_000),
306            Some(Meta::new(FileKind::Directory, false))
307        );
308        assert_eq!(
309            Meta::from_git_mode(0o040_000),
310            Some(Meta::new(FileKind::Directory, false))
311        );
312        assert_eq!(Meta::from_git_mode(0o010_644), None);
313        assert_eq!(Meta::from_git_mode(u32::MAX), None);
314        let compat = Meta::from_git_mode_with(0o100_644, ExecPolicy::PythonCompat);
315        assert_eq!(compat, Some(Meta::regular(cfg!(windows))));
316        assert_eq!(
317            Meta::from_git_mode_with(0o100_644, ExecPolicy::ModeBits),
318            Some(Meta::regular(false))
319        );
320    }
321
322    #[test]
323    fn accessors() {
324        let m = Meta::new(FileKind::Other, true);
325        assert_eq!(m.kind(), FileKind::Other);
326        assert!(m.is_executable());
327        assert!(!m.with_executable(false).is_executable());
328        assert_eq!(ExecPolicy::default(), ExecPolicy::PythonCompat);
329    }
330
331    #[cfg(unix)]
332    #[test]
333    fn unix_exec_policies() -> std::io::Result<()> {
334        use std::os::unix::fs::PermissionsExt;
335        let dir = tempfile::tempdir()?;
336        let path = dir.path().join("f");
337        fs::write(&path, "x")?;
338        let is_root = rustix::process::getuid().is_root();
339        // (mode, PythonCompat for the owner, ModeBits = git's owner bit)
340        for (mode, compat, bits) in [
341            (0o644, false, false),
342            (0o744, true, true),
343            (0o700, true, true),
344            (0o100, true, true),
345            (0o654, is_root, false),
346            (0o645, is_root, false),
347            (0o655, is_root, false),
348            (0o611, is_root, false),
349            (0o755, true, true),
350        ] {
351            fs::set_permissions(&path, fs::Permissions::from_mode(mode))?;
352            let md = fs::symlink_metadata(&path)?;
353            assert_eq!(
354                ExecPolicy::PythonCompat.is_executable(&md),
355                compat,
356                "{mode:o}"
357            );
358            assert_eq!(ExecPolicy::ModeBits.is_executable(&md), bits, "{mode:o}");
359            assert_eq!(
360                Meta::from_metadata(&md, ExecPolicy::PythonCompat),
361                Meta::regular(compat)
362            );
363            // The lstat path agrees with the git index fast path.
364            assert_eq!(
365                Some(Meta::from_metadata(&md, ExecPolicy::ModeBits)),
366                Meta::from_git_mode(0o100_000 | mode),
367                "{mode:o}"
368            );
369        }
370        let md = fs::symlink_metadata(dir.path())?;
371        assert_eq!(
372            Meta::from_metadata(&md, ExecPolicy::PythonCompat),
373            Meta::new(FileKind::Directory, false)
374        );
375        Ok(())
376    }
377}