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}