create src

src-command/Cargo.toml

@@ -0,0 +1,26 @@
+lints.workspace = true
+
+[package]
+name = "src-command"
+version = "0.8.0"
+repository = "https://github.com/GitoxideLabs/gitoxide"
+license = "MIT OR Apache-2.0"
+description = "A crate of the gitoxide project handling internal git command execution"
+authors = ["Sebastian Thiel <sebastian.thiel@icloud.com>"]
+edition = "2021"
+rust-version = "1.82"
+include = ["src/lib.rs", "LICENSE-*"]
+
+[lib]
+doctest = false
+
+[dependencies]
+src-trace = { version = "^0.1.18", path = "../src-trace" }
+src-path = { version = "^0.11.1", path = "../src-path" }
+src-quote = { version = "^0.7.0", path = "../src-quote" }
+
+bstr = { version = "1.12.0", default-features = false, features = ["std", "unicode"] }
+shell-words = "1.1"
+
+[dev-dependencies]
+src-testtools = { path = "../tests/tools" }

src-command/LICENSE-APACHE

@@ -0,0 +1 @@
+../LICENSE-APACHE

src-command/LICENSE-MIT

@@ -0,0 +1 @@
+../LICENSE-MIT

src-command/src/lib.rs

@@ -0,0 +1,562 @@
+//! Launch commands very similarly to `Command`, but with `git` specific capabilities and adjustments.
+#![deny(rust_2018_idioms, missing_docs)]
+#![forbid(unsafe_code)]
+
+use std::{
+    ffi::OsString,
+    io::Read,
+    path::{Path, PathBuf},
+};
+
+use bstr::{BString, ByteSlice};
+
+/// A structure to keep settings to use when invoking a command via [`spawn()`][Prepare::spawn()],
+/// after creating it with [`prepare()`].
+pub struct Prepare {
+    /// The command to invoke, either directly or with a shell depending on `use_shell`.
+    pub command: OsString,
+    /// Additional information to be passed to the spawned command.
+    pub context: Option<Context>,
+    /// The way standard input is configured.
+    pub stdin: std::process::Stdio,
+    /// The way standard output is configured.
+    pub stdout: std::process::Stdio,
+    /// The way standard error is configured.
+    pub stderr: std::process::Stdio,
+    /// The arguments to pass to the process being spawned.
+    pub args: Vec<OsString>,
+    /// Environment variables to set for the spawned process.
+    pub env: Vec<(OsString, OsString)>,
+    /// If `true`, we will use `shell_program` or `sh` to execute the `command`.
+    pub use_shell: bool,
+    /// If `true`, `command` is assumed to be a command or path to the program to execute, and it
+    /// will be shell-quoted to assure it will be executed as is and without splitting across
+    /// whitespace.
+    pub quote_command: bool,
+    /// The name or path to the shell program to use instead of `sh`.
+    pub shell_program: Option<OsString>,
+    /// If `true` (default `true` on Windows and `false` everywhere else) we will see if it's safe
+    /// to manually invoke `command` after splitting its arguments as a shell would do.
+    ///
+    /// Note that outside of Windows, it's generally not advisable as this removes support for
+    /// literal shell scripts with shell-builtins.
+    ///
+    /// This mimics the behaviour we see with `git` on Windows, which also won't invoke the shell
+    /// there at all.
+    ///
+    /// Only effective if `use_shell` is `true` as well, as the shell will be used as a fallback if
+    /// it's not possible to split arguments as the command-line contains 'scripting'.
+    pub allow_manual_arg_splitting: bool,
+}
+
+/// Additional information that is relevant to spawned processes, which typically receive
+/// a wealth of contextual information when spawned from `git`.
+///
+/// See [the git source code](https://github.com/git/git/blob/cfb8a6e9a93adbe81efca66e6110c9b4d2e57169/git.c#L191)
+/// for details.
+#[derive(Debug, Default, Clone)]
+pub struct Context {
+    /// The `.git` directory that contains the repository.
+    ///
+    /// If set, it will be used to set the `GIT_DIR` environment variable.
+    pub git_dir: Option<PathBuf>,
+    /// Set the `GIT_WORK_TREE` environment variable with the given path.
+    pub worktree_dir: Option<PathBuf>,
+    /// If `true`, set `GIT_NO_REPLACE_OBJECTS` to `1`, which turns off object replacements, or `0` otherwise.
+    /// If `None`, the variable won't be set.
+    pub no_replace_objects: Option<bool>,
+    /// Set the `GIT_NAMESPACE` variable with the given value, effectively namespacing all
+    /// operations on references.
+    pub ref_namespace: Option<BString>,
+    /// If `true`, set `GIT_LITERAL_PATHSPECS` to `1`, which makes globs literal and prefixes as well, or `0` otherwise.
+    /// If `None`, the variable won't be set.
+    pub literal_pathspecs: Option<bool>,
+    /// If `true`, set `GIT_GLOB_PATHSPECS` to `1`, which lets wildcards not match the `/` character, and equals the `:(glob)` prefix.
+    /// If `false`, set `GIT_NOGLOB_PATHSPECS` to `1` which lets globs match only themselves.
+    /// If `None`, the variable won't be set.
+    pub glob_pathspecs: Option<bool>,
+    /// If `true`, set `GIT_ICASE_PATHSPECS` to `1`, to let patterns match case-insensitively, or `0` otherwise.
+    /// If `None`, the variable won't be set.
+    pub icase_pathspecs: Option<bool>,
+    /// If `true`, inherit `stderr` just like it's the default when spawning processes.
+    /// If `false`, suppress all stderr output.
+    /// If not `None`, this will override any value set with [`Prepare::stderr()`].
+    pub stderr: Option<bool>,
+}
+
+mod prepare {
+    use std::{
+        borrow::Cow,
+        ffi::OsString,
+        process::{Command, Stdio},
+    };
+
+    use bstr::ByteSlice;
+
+    use crate::{extract_interpreter, win_path_lookup, Context, Prepare};
+
+    /// Builder
+    impl Prepare {
+        /// If called, the command will be checked for characters that are typical for shell
+        /// scripts, and if found will use `sh` to execute it or whatever is set as
+        /// [`with_shell_program()`](Self::with_shell_program()).
+        ///
+        /// If the command isn't valid UTF-8, a shell will always be used.
+        ///
+        /// If a shell is used, then arguments given here with [arg()](Self::arg) or
+        /// [args()](Self::args) will be substituted via `"$@"` if it's not already present in the
+        /// command.
+        ///
+        ///
+        /// The [`command_may_be_shell_script_allow_manual_argument_splitting()`](Self::command_may_be_shell_script_allow_manual_argument_splitting())
+        /// and [`command_may_be_shell_script_disallow_manual_argument_splitting()`](Self::command_may_be_shell_script_disallow_manual_argument_splitting())
+        /// methods also call this method.
+        ///
+        /// If neither this method nor [`with_shell()`](Self::with_shell()) is called, commands are
+        /// always executed verbatim and directly, without the use of a shell.
+        pub fn command_may_be_shell_script(mut self) -> Self {
+            self.use_shell = self
+                .command
+                .to_str()
+                .is_none_or(|cmd| cmd.as_bytes().find_byteset(b"|&;<>()$`\\\"' \t\n*?[#~=%").is_some());
+            self
+        }
+
+        /// If called, unconditionally use a shell to execute the command and its arguments.
+        ///
+        /// This uses `sh` to execute it, or whatever is set as
+        /// [`with_shell_program()`](Self::with_shell_program()).
+        ///
+        /// Arguments given here with [arg()](Self::arg) or [args()](Self::args) will be
+        /// substituted via `"$@"` if it's not already present in the command.
+        ///
+        /// If neither this method nor
+        /// [`command_may_be_shell_script()`](Self::command_may_be_shell_script()) is called,
+        /// commands are always executed verbatim and directly, without the use of a shell. (But
+        /// see [`command_may_be_shell_script()`](Self::command_may_be_shell_script()) on other
+        /// methods that call that method.)
+        ///
+        /// We also disallow manual argument splitting
+        /// (see [`command_may_be_shell_script_disallow_manual_argument_splitting`](Self::command_may_be_shell_script_disallow_manual_argument_splitting()))
+        /// to assure a shell is indeed used, no matter what.
+        pub fn with_shell(mut self) -> Self {
+            self.use_shell = true;
+            self.allow_manual_arg_splitting = false;
+            self
+        }
+
+        /// Quote the command if it is run in a shell, so its path is left intact.
+        ///
+        /// This is only meaningful if the command has been arranged to run in a shell, either
+        /// unconditionally with [`with_shell()`](Self::with_shell()), or conditionally with
+        /// [`command_may_be_shell_script()`](Self::command_may_be_shell_script()).
+        ///
+        /// Note that this should not be used if the command is a script - quoting is only the
+        /// right choice if it's known to be a program path.
+        ///
+        /// Note also that this does not affect arguments passed with [arg()](Self::arg) or
+        /// [args()](Self::args), which do not have to be quoted by the *caller* because they are
+        /// passed as `"$@"` positional parameters (`"$1"`, `"$2"`, and so on).
+        pub fn with_quoted_command(mut self) -> Self {
+            self.quote_command = true;
+            self
+        }
+
+        /// Set the name or path to the shell `program` to use if a shell is to be used, to avoid
+        /// using the default shell which is `sh`.
+        ///
+        /// Note that shells that are not Bourne-style cannot be expected to work correctly,
+        /// because POSIX shell syntax is assumed when searching for and conditionally adding
+        /// `"$@"` to receive arguments, where applicable (and in the behaviour of
+        /// [`with_quoted_command()`](Self::with_quoted_command()), if called).
+        pub fn with_shell_program(mut self, program: impl Into<OsString>) -> Self {
+            self.shell_program = Some(program.into());
+            self
+        }
+
+        /// Unconditionally turn off using the shell when spawning the command.
+        ///
+        /// Note that not using the shell is the default. So an effective use of this method
+        /// is some time after [`command_may_be_shell_script()`](Self::command_may_be_shell_script())
+        /// or [`with_shell()`](Self::with_shell()) was called.
+        pub fn without_shell(mut self) -> Self {
+            self.use_shell = false;
+            self
+        }
+
+        /// Set additional `ctx` to be used when spawning the process.
+        ///
+        /// Note that this is a must for most kind of commands that `git` usually spawns, as at
+        /// least they need to know the correct Git repository to function.
+        pub fn with_context(mut self, ctx: Context) -> Self {
+            self.context = Some(ctx);
+            self
+        }
+
+        /// Like [`command_may_be_shell_script()`](Self::command_may_be_shell_script()), but try to
+        /// split arguments by hand if this can be safely done without a shell.
+        ///
+        /// This is useful on platforms where spawning processes is slow, or where many processes
+        /// have to be spawned in a row which should be sped up. Manual argument splitting is
+        /// enabled by default on Windows only.
+        ///
+        /// Note that this does *not* check for the use of possible shell builtins. Commands may
+        /// fail or behave differently if they are available as shell builtins and no corresponding
+        /// external command exists, or the external command behaves differently.
+        pub fn command_may_be_shell_script_allow_manual_argument_splitting(mut self) -> Self {
+            self.allow_manual_arg_splitting = true;
+            self.command_may_be_shell_script()
+        }
+
+        /// Like [`command_may_be_shell_script()`](Self::command_may_be_shell_script()), but don't
+        /// allow to bypass the shell even if manual argument splitting can be performed safely.
+        pub fn command_may_be_shell_script_disallow_manual_argument_splitting(mut self) -> Self {
+            self.allow_manual_arg_splitting = false;
+            self.command_may_be_shell_script()
+        }
+
+        /// Configure the process to use `stdio` for _stdin_.
+        pub fn stdin(mut self, stdio: Stdio) -> Self {
+            self.stdin = stdio;
+            self
+        }
+        /// Configure the process to use `stdio` for _stdout_.
+        pub fn stdout(mut self, stdio: Stdio) -> Self {
+            self.stdout = stdio;
+            self
+        }
+        /// Configure the process to use `stdio` for _stderr_.
+        pub fn stderr(mut self, stdio: Stdio) -> Self {
+            self.stderr = stdio;
+            self
+        }
+
+        /// Add `arg` to the list of arguments to call the command with.
+        pub fn arg(mut self, arg: impl Into<OsString>) -> Self {
+            self.args.push(arg.into());
+            self
+        }
+
+        /// Add `args` to the list of arguments to call the command with.
+        pub fn args(mut self, args: impl IntoIterator<Item = impl Into<OsString>>) -> Self {
+            self.args
+                .append(&mut args.into_iter().map(Into::into).collect::<Vec<_>>());
+            self
+        }
+
+        /// Add `key` with `value` to the environment of the spawned command.
+        pub fn env(mut self, key: impl Into<OsString>, value: impl Into<OsString>) -> Self {
+            self.env.push((key.into(), value.into()));
+            self
+        }
+    }
+
+    /// Finalization
+    impl Prepare {
+        /// Spawn the command as configured.
+        pub fn spawn(self) -> std::io::Result<std::process::Child> {
+            let mut cmd = Command::from(self);
+            gix_trace::debug!(cmd = ?cmd);
+            cmd.spawn()
+        }
+    }
+
+    impl From<Prepare> for Command {
+        fn from(mut prep: Prepare) -> Command {
+            let mut cmd = if prep.use_shell {
+                let split_args = prep
+                    .allow_manual_arg_splitting
+                    .then(|| {
+                        if gix_path::into_bstr(std::borrow::Cow::Borrowed(prep.command.as_ref()))
+                            .find_byteset(b"\\|&;<>()$`\n*?[#~%")
+                            .is_none()
+                        {
+                            prep.command
+                                .to_str()
+                                .and_then(|args| shell_words::split(args).ok().map(Vec::into_iter))
+                        } else {
+                            None
+                        }
+                    })
+                    .flatten();
+                match split_args {
+                    Some(mut args) => {
+                        let mut cmd = Command::new(args.next().expect("non-empty input"));
+                        cmd.args(args);
+                        cmd
+                    }
+                    None => {
+                        let shell = prep.shell_program.unwrap_or_else(|| gix_path::env::shell().into());
+                        let mut cmd = Command::new(shell);
+                        cmd.arg("-c");
+                        if !prep.args.is_empty() {
+                            if prep.command.to_str().is_none_or(|cmd| !cmd.contains("$@")) {
+                                if prep.quote_command {
+                                    if let Ok(command) = gix_path::os_str_into_bstr(&prep.command) {
+                                        prep.command = gix_path::from_bstring(gix_quote::single(command)).into();
+                                    }
+                                }
+                                prep.command.push(r#" "$@""#);
+                            } else {
+                                gix_trace::debug!(
+                                    r#"Will not add '"$@"' to '{:?}' as it seems to contain '$@' already"#,
+                                    prep.command
+                                );
+                            }
+                        }
+                        cmd.arg(prep.command);
+                        cmd.arg("--");
+                        cmd
+                    }
+                }
+            } else if cfg!(windows) {
+                let program: Cow<'_, std::path::Path> = std::env::var_os("PATH")
+                    .and_then(|path| win_path_lookup(prep.command.as_ref(), &path))
+                    .map(Cow::Owned)
+                    .unwrap_or(Cow::Borrowed(prep.command.as_ref()));
+                if let Some(shebang) = extract_interpreter(program.as_ref()) {
+                    let mut cmd = Command::new(shebang.interpreter);
+                    // For relative paths, we may have picked up a file in the current repository
+                    // for which an attacker could control everything. Hence, strip options just like Git.
+                    // If the file was found in the PATH though, it should be trustworthy.
+                    if program.is_absolute() {
+                        cmd.args(shebang.args);
+                    }
+                    cmd.arg(prep.command);
+                    cmd
+                } else {
+                    Command::new(prep.command)
+                }
+            } else {
+                Command::new(prep.command)
+            };
+            // We never want to have terminals pop-up on Windows if this runs from a GUI application.
+            #[cfg(windows)]
+            {
+                use std::os::windows::process::CommandExt;
+                const CREATE_NO_WINDOW: u32 = 0x08000000;
+                cmd.creation_flags(CREATE_NO_WINDOW);
+            }
+            cmd.stdin(prep.stdin)
+                .stdout(prep.stdout)
+                .stderr(prep.stderr)
+                .envs(prep.env)
+                .args(prep.args);
+            if let Some(ctx) = prep.context {
+                if let Some(git_dir) = ctx.git_dir {
+                    cmd.env("GIT_DIR", &git_dir);
+                }
+                if let Some(worktree_dir) = ctx.worktree_dir {
+                    cmd.env("GIT_WORK_TREE", worktree_dir);
+                }
+                if let Some(value) = ctx.no_replace_objects {
+                    cmd.env("GIT_NO_REPLACE_OBJECTS", usize::from(value).to_string());
+                }
+                if let Some(namespace) = ctx.ref_namespace {
+                    cmd.env("GIT_NAMESPACE", gix_path::from_bstring(namespace));
+                }
+                if let Some(value) = ctx.literal_pathspecs {
+                    cmd.env("GIT_LITERAL_PATHSPECS", usize::from(value).to_string());
+                }
+                if let Some(value) = ctx.glob_pathspecs {
+                    cmd.env(
+                        if value {
+                            "GIT_GLOB_PATHSPECS"
+                        } else {
+                            "GIT_NOGLOB_PATHSPECS"
+                        },
+                        "1",
+                    );
+                }
+                if let Some(value) = ctx.icase_pathspecs {
+                    cmd.env("GIT_ICASE_PATHSPECS", usize::from(value).to_string());
+                }
+                if let Some(stderr) = ctx.stderr {
+                    cmd.stderr(if stderr { Stdio::inherit() } else { Stdio::null() });
+                }
+            }
+            cmd
+        }
+    }
+}
+
+fn is_exe(executable: &Path) -> bool {
+    executable.extension() == Some(std::ffi::OsStr::new("exe"))
+}
+
+/// Try to find `command` in the `path_value` (the value of `PATH`) as separated by `;`, or return `None`.
+/// Has special handling for `.exe` extensions, as these will be appended automatically if needed.
+/// Note that just like Git, no lookup is performed if a slash or backslash is in `command`.
+fn win_path_lookup(command: &Path, path_value: &std::ffi::OsStr) -> Option<PathBuf> {
+    fn lookup(root: &bstr::BStr, command: &Path, is_exe: bool) -> Option<PathBuf> {
+        let mut path = gix_path::try_from_bstr(root).ok()?.join(command);
+        if !is_exe {
+            path.set_extension("exe");
+        }
+        if path.is_file() {
+            return Some(path);
+        }
+        if is_exe {
+            return None;
+        }
+        path.set_extension("");
+        path.is_file().then_some(path)
+    }
+    if command.components().take(2).count() == 2 {
+        return None;
+    }
+    let path = gix_path::os_str_into_bstr(path_value).ok()?;
+    let is_exe = is_exe(command);
+
+    for root in path.split(|b| *b == b';') {
+        if let Some(executable) = lookup(root.as_bstr(), command, is_exe) {
+            return Some(executable);
+        }
+    }
+    None
+}
+
+/// Parse the shebang (`#!<path>`) from the first line of `executable`, and return the shebang
+/// data when available.
+pub fn extract_interpreter(executable: &Path) -> Option<shebang::Data> {
+    #[cfg(windows)]
+    if is_exe(executable) {
+        return None;
+    }
+    let mut buf = [0; 100]; // Note: just like Git
+    let mut file = std::fs::File::open(executable).ok()?;
+    let n = file.read(&mut buf).ok()?;
+    shebang::parse(buf[..n].as_bstr())
+}
+
+///
+pub mod shebang {
+    use std::{ffi::OsString, path::PathBuf};
+
+    use bstr::{BStr, ByteSlice};
+
+    /// Parse `buf` to extract all shebang information.
+    pub fn parse(buf: &BStr) -> Option<Data> {
+        let mut line = buf.lines().next()?;
+        line = line.strip_prefix(b"#!")?;
+
+        let slash_idx = line.rfind_byteset(br"/\")?;
+        Some(match line[slash_idx..].find_byte(b' ') {
+            Some(space_idx) => {
+                let space = slash_idx + space_idx;
+                Data {
+                    interpreter: gix_path::from_byte_slice(line[..space].trim()).to_owned(),
+                    args: line
+                        .get(space + 1..)
+                        .and_then(|mut r| {
+                            r = r.trim();
+                            if r.is_empty() {
+                                return None;
+                            }
+
+                            match r.as_bstr().to_str() {
+                                Ok(args) => shell_words::split(args)
+                                    .ok()
+                                    .map(|args| args.into_iter().map(Into::into).collect()),
+                                Err(_) => Some(vec![gix_path::from_byte_slice(r).to_owned().into()]),
+                            }
+                        })
+                        .unwrap_or_default(),
+                }
+            }
+            None => Data {
+                interpreter: gix_path::from_byte_slice(line.trim()).to_owned(),
+                args: Vec::new(),
+            },
+        })
+    }
+
+    /// Shebang information as [parsed](parse()) from a buffer that should contain at least one line.
+    ///
+    /// ### Deviation
+    ///
+    /// According to the [shebang documentation](https://en.wikipedia.org/wiki/Shebang_(Unix)), it will only consider
+    /// the path of the executable, along with the arguments as the consecutive portion after the space that separates
+    /// them. Argument splitting would then have to be done elsewhere, probably in the kernel.
+    ///
+    /// To make that work without the kernel, we perform the splitting while Git just ignores options.
+    /// For now it seems more compatible to not ignore options, but if it is important this could be changed.
+    #[derive(Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Hash)]
+    pub struct Data {
+        /// The interpreter to run.
+        pub interpreter: PathBuf,
+        /// The remainder of the line past the space after `interpreter`, without leading or trailing whitespace,
+        /// as pre-split arguments just like a shell would do it.
+        /// Note that we accept that illformed UTF-8 will prevent argument splitting.
+        pub args: Vec<OsString>,
+    }
+}
+
+/// Prepare `cmd` for [spawning][std::process::Command::spawn()] by configuring it with various builder methods.
+///
+/// Note that the default IO is configured for typical API usage, that is
+///
+/// - `stdin` is null to prevent blocking unexpectedly on consumption of stdin
+/// - `stdout` is captured for consumption by the caller
+/// - `stderr` is inherited to allow the command to provide context to the user
+///
+/// On Windows, terminal Windows will be suppressed automatically.
+///
+/// ### Warning
+///
+/// When using this method, be sure that the invoked program doesn't rely on the current working dir and/or
+/// environment variables to know its context. If so, call instead [`Prepare::with_context()`] to provide
+/// additional information.
+pub fn prepare(cmd: impl Into<OsString>) -> Prepare {
+    Prepare {
+        command: cmd.into(),
+        shell_program: None,
+        context: None,
+        stdin: std::process::Stdio::null(),
+        stdout: std::process::Stdio::piped(),
+        stderr: std::process::Stdio::inherit(),
+        args: Vec::new(),
+        env: Vec::new(),
+        use_shell: false,
+        quote_command: false,
+        allow_manual_arg_splitting: cfg!(windows),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn internal_win_path_lookup() -> gix_testtools::Result {
+        let root = gix_testtools::scripted_fixture_read_only("win_path_lookup.sh")?;
+        let mut paths: Vec<_> = std::fs::read_dir(&root)?
+            .filter_map(Result::ok)
+            .map(|e| e.path().to_str().expect("no illformed UTF8").to_owned())
+            .collect();
+        paths.sort();
+        let lookup_path: OsString = paths.join(";").into();
+
+        assert_eq!(
+            win_path_lookup("a/b".as_ref(), &lookup_path),
+            None,
+            "any path with separator is considered ready to use"
+        );
+        assert_eq!(
+            win_path_lookup("x".as_ref(), &lookup_path),
+            Some(root.join("a").join("x.exe")),
+            "exe will be preferred, and it searches left to right thus doesn't find c/x.exe"
+        );
+        assert_eq!(
+            win_path_lookup("x.exe".as_ref(), &lookup_path),
+            Some(root.join("a").join("x.exe")),
+            "no matter what, a/x won't be found as it's shadowed by an exe file"
+        );
+        assert_eq!(
+            win_path_lookup("exe".as_ref(), &lookup_path),
+            Some(root.join("b").join("exe")),
+            "it finds files further down the path as well"
+        );
+        Ok(())
+    }
+}

src-command/tests/command.rs

@@ -0,0 +1,636 @@
+use std::path::Path;
+
+use gix_testtools::Result;
+
+#[test]
+fn extract_interpreter() -> gix_testtools::Result {
+    let root = gix_testtools::scripted_fixture_read_only("win_path_lookup.sh")?;
+    assert_eq!(
+        gix_command::extract_interpreter(&root.join("b").join("exe")),
+        Some(gix_command::shebang::Data {
+            interpreter: Path::new("/b/exe").into(),
+            args: vec![]
+        })
+    );
+    Ok(())
+}
+
+mod shebang {
+    mod parse {
+        use gix_command::shebang;
+
+        fn parse(input: &str) -> Option<shebang::Data> {
+            shebang::parse(input.into())
+        }
+
+        fn exe(name: &str) -> Option<shebang::Data> {
+            shebang::Data {
+                interpreter: name.into(),
+                args: Vec::new(),
+            }
+            .into()
+        }
+
+        fn exe_arg(name: &str, arg: &str) -> Option<shebang::Data> {
+            shebang::Data {
+                interpreter: name.into(),
+                args: shell_words::split(arg)
+                    .expect("can parse")
+                    .into_iter()
+                    .map(Into::into)
+                    .collect(),
+            }
+            .into()
+        }
+
+        #[test]
+        fn valid() {
+            assert_eq!(parse("#!/bin/sh"), exe("/bin/sh"));
+            assert_eq!(parse("#!/bin/sh   "), exe("/bin/sh"), "trim trailing whitespace");
+            assert_eq!(
+                parse("#!/bin/sh\t\nother"),
+                exe("/bin/sh"),
+                "trimming works for tabs as well"
+            );
+            assert_eq!(
+                parse(r"#!\bin\sh"),
+                exe(r"\bin\sh"),
+                "backslashes are recognized as path separator"
+            );
+            assert_eq!(
+                parse("#!C:\\Program Files\\shell.exe\r\nsome stuff"),
+                exe(r"C:\Program Files\shell.exe"),
+                "absolute windows paths are fine"
+            );
+            assert_eq!(
+                parse("#!/bin/sh -i -o -u\nunrelated content"),
+                exe_arg("/bin/sh", "-i -o -u"),
+                "argument splitting happens as well"
+            );
+            assert_eq!(
+                parse("#!/bin/sh  -o\nunrelated content"),
+                exe_arg("/bin/sh", "-o"),
+                "single arguments are OK too"
+            );
+            assert_eq!(
+                parse("#!/bin/exe anything goes\nunrelated content"),
+                exe_arg("/bin/exe", "anything goes"),
+                "any argument works"
+            );
+
+            #[cfg(unix)]
+            {
+                use std::os::unix::ffi::OsStrExt;
+
+                use bstr::ByteSlice;
+                assert_eq!(
+                    shebang::parse(b"#!/bin/sh   -x \xC3\x28\x41 -y  ".as_bstr()),
+                    Some(shebang::Data {
+                        interpreter: "/bin/sh".into(),
+                        args: vec![std::ffi::OsStr::from_bytes(b"-x \xC3\x28\x41 -y").to_owned()]
+                    }),
+                    "illformed UTF8 in the arguments leads to them not being split - useful in case it's just one path or so"
+                );
+
+                assert_eq!(
+                    shebang::parse(b"#!/bin/\xC3\x28\x41 ".as_bstr()),
+                    Some(shebang::Data {
+                        interpreter: std::ffi::OsStr::from_bytes(b"/bin/\xC3\x28\x41").to_owned().into(),
+                        args: vec![]
+                    }),
+                    "illformed UTF8 in the executable path is fine as well"
+                );
+            }
+        }
+
+        #[test]
+        fn invalid() {
+            assert_eq!(parse(""), None);
+            assert_eq!(parse("missing shebang"), None);
+            assert_eq!(parse("#!missing-slash"), None);
+            assert_eq!(
+                parse("/bin/sh"),
+                None,
+                "shebang missing, even though a valid path is given"
+            );
+        }
+    }
+}
+
+mod context {
+    use gix_command::Context;
+
+    fn winfix(expected: impl Into<String>) -> String {
+        // Unclear why it's not debug-printing the env on windows.
+        if cfg!(windows) {
+            "\"\"".into()
+        } else {
+            expected.into()
+        }
+    }
+
+    #[test]
+    fn git_dir_sets_git_dir_env_and_cwd() {
+        let ctx = Context {
+            git_dir: Some(".".into()),
+            ..Default::default()
+        };
+        let cmd = std::process::Command::from(gix_command::prepare("").with_context(ctx));
+        assert_eq!(format!("{cmd:?}"), winfix(r#"GIT_DIR="." """#));
+    }
+
+    #[test]
+    fn worktree_dir_sets_env_only() {
+        let ctx = Context {
+            worktree_dir: Some(".".into()),
+            ..Default::default()
+        };
+        let cmd = std::process::Command::from(gix_command::prepare("").with_context(ctx));
+        assert_eq!(format!("{cmd:?}"), winfix(r#"GIT_WORK_TREE="." """#));
+    }
+
+    #[test]
+    fn no_replace_objects_sets_env_only() {
+        for value in [false, true] {
+            let expected = usize::from(value);
+            let ctx = Context {
+                no_replace_objects: Some(value),
+                ..Default::default()
+            };
+            let cmd = std::process::Command::from(gix_command::prepare("").with_context(ctx));
+            assert_eq!(
+                format!("{cmd:?}"),
+                winfix(format!(r#"GIT_NO_REPLACE_OBJECTS="{expected}" """#))
+            );
+        }
+    }
+
+    #[test]
+    fn ref_namespace_sets_env_only() {
+        let ctx = Context {
+            ref_namespace: Some("namespace".into()),
+            ..Default::default()
+        };
+        let cmd = std::process::Command::from(gix_command::prepare("").with_context(ctx));
+        assert_eq!(format!("{cmd:?}"), winfix(r#"GIT_NAMESPACE="namespace" """#));
+    }
+
+    #[test]
+    fn literal_pathspecs_sets_env_only() {
+        for value in [false, true] {
+            let expected = usize::from(value);
+            let ctx = Context {
+                literal_pathspecs: Some(value),
+                ..Default::default()
+            };
+            let cmd = std::process::Command::from(gix_command::prepare("").with_context(ctx));
+            assert_eq!(
+                format!("{cmd:?}"),
+                winfix(format!(r#"GIT_LITERAL_PATHSPECS="{expected}" """#))
+            );
+        }
+    }
+
+    #[test]
+    fn glob_pathspecs_sets_env_only() {
+        for (value, expected) in [
+            (false, r#"GIT_NOGLOB_PATHSPECS="1""#),
+            (true, r#"GIT_GLOB_PATHSPECS="1""#),
+        ] {
+            let ctx = Context {
+                glob_pathspecs: Some(value),
+                ..Default::default()
+            };
+            let cmd = std::process::Command::from(gix_command::prepare("").with_context(ctx));
+            assert_eq!(format!("{cmd:?}"), winfix(format!(r#"{expected} """#)));
+        }
+    }
+
+    #[test]
+    fn icase_pathspecs_sets_env_only() {
+        for value in [false, true] {
+            let expected = usize::from(value);
+            let ctx = Context {
+                icase_pathspecs: Some(value),
+                ..Default::default()
+            };
+            let cmd = std::process::Command::from(gix_command::prepare("").with_context(ctx));
+            assert_eq!(
+                format!("{cmd:?}"),
+                winfix(format!(r#"GIT_ICASE_PATHSPECS="{expected}" """#))
+            );
+        }
+    }
+}
+
+mod prepare {
+    use std::sync::LazyLock;
+
+    static SH: LazyLock<&'static str> = LazyLock::new(|| {
+        gix_path::env::shell()
+            .to_str()
+            .expect("`prepare` tests must be run where 'sh' path is valid Unicode")
+    });
+
+    fn quoted(input: &[&str]) -> String {
+        input.iter().map(|s| format!("\"{s}\"")).collect::<Vec<_>>().join(" ")
+    }
+
+    #[test]
+    fn empty() {
+        let cmd = std::process::Command::from(gix_command::prepare(""));
+        assert_eq!(format!("{cmd:?}"), "\"\"");
+    }
+
+    #[test]
+    fn single_and_multiple_arguments() {
+        let cmd = std::process::Command::from(gix_command::prepare("ls").arg("first").args(["second", "third"]));
+        assert_eq!(format!("{cmd:?}"), quoted(&["ls", "first", "second", "third"]));
+    }
+
+    #[test]
+    fn multiple_arguments_in_one_line_with_auto_split() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare("echo first second third")
+                .command_may_be_shell_script_allow_manual_argument_splitting(),
+        );
+        assert_eq!(
+            format!("{cmd:?}"),
+            quoted(&["echo", "first", "second", "third"]),
+            "we split by hand which works unless one tries to rely on shell-builtins (which we can't detect)"
+        );
+    }
+
+    #[test]
+    fn single_and_multiple_arguments_as_part_of_command() {
+        let cmd = std::process::Command::from(gix_command::prepare("ls first second third"));
+        assert_eq!(
+            format!("{cmd:?}"),
+            quoted(&["ls first second third"]),
+            "without shell, this is an invalid command"
+        );
+    }
+
+    #[test]
+    fn single_and_multiple_arguments_as_part_of_command_with_shell() {
+        let cmd =
+            std::process::Command::from(gix_command::prepare("ls first second third").command_may_be_shell_script());
+        assert_eq!(
+            format!("{cmd:?}"),
+            if cfg!(windows) {
+                quoted(&["ls", "first", "second", "third"])
+            } else {
+                quoted(&[*SH, "-c", "ls first second third", "--"])
+            },
+            "with shell, this works as it performs word splitting"
+        );
+    }
+
+    #[test]
+    fn single_and_multiple_arguments_as_part_of_command_with_given_shell() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare("ls first second third")
+                .command_may_be_shell_script()
+                .with_shell_program("/somepath/to/bash"),
+        );
+        assert_eq!(
+            format!("{cmd:?}"),
+            if cfg!(windows) {
+                quoted(&["ls", "first", "second", "third"])
+            } else {
+                quoted(&["/somepath/to/bash", "-c", "ls first second third", "--"])
+            },
+            "with shell, this works as it performs word splitting on Windows, but on linux (or without splitting) it uses the given shell"
+        );
+    }
+
+    #[test]
+    fn single_and_complex_arguments_as_part_of_command_with_shell() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare(r#"ls --foo "a b""#)
+                .arg("additional")
+                .command_may_be_shell_script(),
+        );
+        assert_eq!(
+            format!("{cmd:?}"),
+            if cfg!(windows) {
+                quoted(&["ls", "--foo", "a b", "additional"])
+            } else {
+                let sh = *SH;
+                format!(r#""{sh}" "-c" "ls --foo \"a b\" \"$@\"" "--" "additional""#)
+            },
+            "with shell, this works as it performs word splitting, on windows we can avoid the shell"
+        );
+    }
+
+    #[test]
+    fn single_and_complex_arguments_with_auto_split() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare(r#"ls --foo="a b""#).command_may_be_shell_script_allow_manual_argument_splitting(),
+        );
+        assert_eq!(
+            format!("{cmd:?}"),
+            format!(r#""ls" "--foo=a b""#),
+            "splitting can also handle quotes"
+        );
+    }
+
+    #[test]
+    fn single_and_complex_arguments_without_auto_split() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare(r#"ls --foo="a b""#).command_may_be_shell_script_disallow_manual_argument_splitting(),
+        );
+        assert_eq!(format!("{cmd:?}"), quoted(&[*SH, "-c", r#"ls --foo=\"a b\""#, "--"]));
+    }
+
+    #[test]
+    fn single_and_simple_arguments_without_auto_split_with_shell() {
+        let cmd = std::process::Command::from(gix_command::prepare("ls").arg("--foo=a b").with_shell());
+        assert_eq!(
+            format!("{cmd:?}"),
+            quoted(&[*SH, "-c", r#"ls \"$@\""#, "--", "--foo=a b"])
+        );
+    }
+
+    #[test]
+    fn quoted_command_without_argument_splitting() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare("ls")
+                .arg("--foo=a b")
+                .with_shell()
+                .with_quoted_command(),
+        );
+        assert_eq!(
+            format!("{cmd:?}"),
+            quoted(&[*SH, "-c", r#"'ls' \"$@\""#, "--", "--foo=a b"]),
+            "looks strange thanks to debug printing, but is the right amount of quotes actually"
+        );
+    }
+
+    #[test]
+    fn quoted_windows_command_without_argument_splitting() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare(r"C:\Users\O'Shaughnessy\with space.exe")
+                .arg("--foo='a b'")
+                .with_shell()
+                .with_quoted_command(),
+        );
+        assert_eq!(
+            format!("{cmd:?}"),
+            quoted(&[
+                *SH,
+                "-c",
+                r#"'C:\\Users\\O'\\''Shaughnessy\\with space.exe' \"$@\""#,
+                "--",
+                r"--foo='a b'"
+            ]),
+            "again, a lot of extra backslashes, but it's correct outside of the debug formatting"
+        );
+    }
+
+    #[test]
+    fn single_and_complex_arguments_will_not_auto_split_on_special_characters() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare("ls --foo=~/path").command_may_be_shell_script_allow_manual_argument_splitting(),
+        );
+        let sh = *SH;
+        assert_eq!(
+            format!("{cmd:?}"),
+            format!(r#""{sh}" "-c" "ls --foo=~/path" "--""#),
+            "splitting can also handle quotes"
+        );
+    }
+
+    #[test]
+    fn tilde_path_and_multiple_arguments_as_part_of_command_with_shell() {
+        let cmd =
+            std::process::Command::from(gix_command::prepare(r#"~/bin/exe --foo "a b""#).command_may_be_shell_script());
+        let sh = *SH;
+        assert_eq!(
+            format!("{cmd:?}"),
+            format!(r#""{sh}" "-c" "~/bin/exe --foo \"a b\"" "--""#),
+            "this always needs a shell as we need tilde expansion"
+        );
+    }
+
+    #[test]
+    fn script_with_dollar_at() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare(r#"echo "$@" >&2"#)
+                .command_may_be_shell_script()
+                .arg("store"),
+        );
+        let sh = *SH;
+        assert_eq!(
+            format!("{cmd:?}"),
+            format!(r#""{sh}" "-c" "echo \"$@\" >&2" "--" "store""#),
+            "this is how credential helpers have to work as for some reason they don't get '$@' added in Git.\
+            We deal with it by not doubling the '$@' argument, which seems more flexible."
+        );
+    }
+
+    #[test]
+    fn script_with_dollar_at_has_no_quoting() {
+        let cmd = std::process::Command::from(
+            gix_command::prepare(r#"echo "$@" >&2"#)
+                .command_may_be_shell_script()
+                .with_quoted_command()
+                .arg("store"),
+        );
+        let sh = *SH;
+        assert_eq!(
+            format!("{cmd:?}"),
+            format!(r#""{sh}" "-c" "echo \"$@\" >&2" "--" "store""#)
+        );
+    }
+}
+
+mod spawn {
+    use bstr::ByteSlice;
+
+    #[test]
+    fn environment_variables_are_passed_one_by_one() -> crate::Result {
+        let out = gix_command::prepare("echo $FIRST $SECOND")
+            .env("FIRST", "first")
+            .env("SECOND", "second")
+            .command_may_be_shell_script()
+            .spawn()?
+            .wait_with_output()?;
+        assert_eq!(out.stdout.as_bstr(), "first second\n");
+        Ok(())
+    }
+
+    #[test]
+    fn disallow_shell() -> crate::Result {
+        let out = gix_command::prepare("PATH= echo hi")
+            .command_may_be_shell_script_disallow_manual_argument_splitting()
+            .spawn()?
+            .wait_with_output()?;
+        assert_eq!(out.stdout.as_bstr(), "hi\n");
+
+        let mut cmd: std::process::Command = gix_command::prepare("echo hi")
+            .command_may_be_shell_script()
+            .without_shell()
+            .into();
+        assert!(
+            cmd.env_remove("PATH").spawn().is_err(),
+            "no command named 'echo hi' exists"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn script_with_dollar_at() -> crate::Result {
+        let out = std::process::Command::from(
+            gix_command::prepare(r#"echo "$@""#)
+                .command_may_be_shell_script()
+                .arg("arg"),
+        )
+        .spawn()?
+        .wait_with_output()?;
+        assert_eq!(
+            out.stdout.to_str_lossy().trim(),
+            "arg",
+            "the argument is just mentioned once"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn direct_command_execution_searches_in_path() -> crate::Result {
+        assert!(gix_command::prepare(if cfg!(unix) { "ls" } else { "attrib.exe" })
+            .spawn()?
+            .wait()?
+            .success());
+        Ok(())
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn direct_command_with_absolute_command_path() -> crate::Result {
+        assert!(gix_command::prepare("/usr/bin/env").spawn()?.wait()?.success());
+        Ok(())
+    }
+
+    mod with_shell {
+        use gix_testtools::bstr::ByteSlice;
+
+        #[test]
+        fn command_in_path_with_args() -> crate::Result {
+            // `ls` is occasionaly a builtin, as in busybox ash, but it is usually external.
+            assert!(gix_command::prepare(if cfg!(unix) { "ls -l" } else { "attrib.exe /d" })
+                .command_may_be_shell_script()
+                .spawn()?
+                .wait()?
+                .success());
+            Ok(())
+        }
+
+        #[cfg(unix)]
+        #[test]
+        fn shell_builtin_or_command_in_path() -> crate::Result {
+            let out = gix_command::prepare("echo")
+                .command_may_be_shell_script()
+                .spawn()?
+                .wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "\n");
+            Ok(())
+        }
+
+        #[cfg(unix)]
+        #[test]
+        fn shell_builtin_or_command_in_path_with_single_extra_arg() -> crate::Result {
+            let out = gix_command::prepare("printf")
+                .command_may_be_shell_script()
+                .arg("1")
+                .spawn()?
+                .wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "1");
+            Ok(())
+        }
+
+        #[cfg(unix)]
+        #[test]
+        fn shell_builtin_or_command_in_path_with_multiple_extra_args() -> crate::Result {
+            let out = gix_command::prepare("printf")
+                .command_may_be_shell_script()
+                .arg("%s")
+                .arg("arg")
+                .spawn()?
+                .wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "arg");
+            Ok(())
+        }
+
+        #[test]
+        fn force_shell_builtin() -> crate::Result {
+            let out = gix_command::prepare("echo").with_shell().spawn()?.wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "\n");
+            Ok(())
+        }
+
+        #[test]
+        fn force_shell_builtin_with_single_extra_arg() -> crate::Result {
+            let out = gix_command::prepare("printf")
+                .with_shell()
+                .arg("1")
+                .spawn()?
+                .wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "1");
+            Ok(())
+        }
+
+        #[test]
+        fn force_shell_builtin_with_multiple_extra_args() -> crate::Result {
+            let out = gix_command::prepare("printf")
+                .with_shell()
+                .arg("%s")
+                .arg("arg")
+                .spawn()?
+                .wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "arg");
+            Ok(())
+        }
+
+        #[test]
+        fn sh_shell_specific_script_code() -> crate::Result {
+            assert!(gix_command::prepare(":;:;:")
+                .command_may_be_shell_script()
+                .spawn()?
+                .wait()?
+                .success());
+            Ok(())
+        }
+
+        #[test]
+        fn sh_shell_specific_script_code_with_single_extra_arg() -> crate::Result {
+            let out = gix_command::prepare(":;printf")
+                .command_may_be_shell_script()
+                .arg("1")
+                .spawn()?
+                .wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "1");
+            Ok(())
+        }
+
+        #[test]
+        fn sh_shell_specific_script_code_with_multiple_extra_args() -> crate::Result {
+            let out = gix_command::prepare(":;printf")
+                .command_may_be_shell_script()
+                .arg("%s")
+                .arg("arg")
+                .spawn()?
+                .wait_with_output()?;
+            assert!(out.status.success());
+            assert_eq!(out.stdout.as_bstr(), "arg");
+            Ok(())
+        }
+    }
+}

src-command/tests/fixtures/generated-archives/.gitignore

@@ -0,0 +1 @@
+win_path_lookup.tar

src-command/tests/fixtures/win_path_lookup.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -eu -o pipefail
+
+mkdir a b c
+echo "#!/a/x.exe" > a/x.exe
+echo "#!/a/x" > a/x
+echo "#!/b/exe" > b/exe
+echo "#!/b/exe.com" > b/exe.com
+echo "#!/c/x.exe" > c/x.exe