docs: warn about unsupported Git configuration settings

Author: arxanas

git-branchless-lib/src/git/repo.rs

@@ -52,6 +52,9 @@ pub enum Error {
     #[error("could not open repository: {0}")]
     OpenRepo(#[source] git2::Error),
 
+    #[error("could not open repository: {0}")]
+    UnsupportedExtensionWorktreeConfig(#[source] git2::Error),
+
     #[error("could not read index: {0}")]
     ReadIndex(#[source] git2::Error),
 
@@ -457,7 +460,18 @@ impl Repo {
     /// Get the Git repository associated with the given directory.
     #[instrument]
     pub fn from_dir(path: &Path) -> Result<Self> {
-        let repo = git2::Repository::discover(path).map_err(Error::OpenRepo)?;
+        let repo = match git2::Repository::discover(path) {
+            Ok(repo) => repo,
+            Err(err)
+                if err.code() == git2::ErrorCode::GenericError
+                    && err
+                        .message()
+                        .contains("unsupported extension name extensions.worktreeconfig") =>
+            {
+                return Err(Error::UnsupportedExtensionWorktreeConfig(err))
+            }
+            Err(err) => return Err(Error::OpenRepo(err)),
+        };
         Ok(Repo { inner: repo })
     }
 

git-branchless/src/commands/mod.rs

@@ -23,13 +23,19 @@ mod wrap;
 use std::any::Any;
 use std::convert::TryInto;
 use std::ffi::OsString;
+use std::fmt::Write;
 use std::path::PathBuf;
 use std::time::SystemTime;
 
 use clap::Parser;
+use cursive::theme::BaseColor;
+use cursive::utils::markup::StyledString;
 use eyre::Context;
 use itertools::Itertools;
+use lib::core::formatting::printable_styled_string;
 use lib::core::rewrite::MergeConflictRemediation;
+use lib::git::Repo;
+use lib::git::RepoError;
 use lib::util::ExitCode;
 use tracing_chrome::ChromeLayerBuilder;
 use tracing_error::ErrorLayer;
@@ -119,6 +125,11 @@ fn do_main_and_drop_locals() -> eyre::Result<i32> {
     };
     let effects = Effects::new(color);
 
+    if let Some(ExitCode(exit_code)) = check_unsupported_config_options(&effects)? {
+        let exit_code: i32 = exit_code.try_into()?;
+        return Ok(exit_code);
+    }
+
     let ExitCode(exit_code) = match command {
         Command::Amend { move_options } => amend::amend(&effects, &git_run_info, &move_options)?,
 
@@ -433,6 +444,43 @@ fn install_tracing() -> eyre::Result<impl Drop> {
     Ok(flush_guard)
 }
 
+fn check_unsupported_config_options(effects: &Effects) -> eyre::Result<Option<ExitCode>> {
+    let _repo = match Repo::from_current_dir() {
+        Ok(repo) => repo,
+        Err(RepoError::UnsupportedExtensionWorktreeConfig(_)) => {
+            writeln!(
+                effects.get_output_stream(),
+                "\
+{error}
+
+Usually, this configuration setting is enabled when initializing a sparse
+checkout. See https://github.com/arxanas/git-branchless/issues/278 for more
+information.
+
+Here are some options:
+
+- To unset the configuration option, run: git config --unset extensions.worktreeConfig
+  - This is safe unless you created another worktree also using a sparse checkout.
+- Try upgrading to Git v2.36+ and reinitializing your sparse checkout.",
+                error = printable_styled_string(
+                    effects.get_glyphs(),
+                    StyledString::styled(
+                        "\
+Error: the Git configuration setting `extensions.worktreeConfig` is enabled in
+this repository. Due to upstream libgit2 limitations, git-branchless does not
+support repositories with this configuration option enabled.",
+                        BaseColor::Red.light()
+                    )
+                )?,
+            )?;
+            return Ok(Some(ExitCode(1)));
+        }
+        Err(_) => return Ok(None),
+    };
+
+    Ok(None)
+}
+
 /// Re-exports of internals for testing purposes.
 pub mod testing {
     pub use crate::commands::undo::testing as undo;

git-branchless/tests/test_branchless.rs

@@ -83,3 +83,50 @@ fn test_profiling() -> eyre::Result<()> {
 
     Ok(())
 }
+
+#[test]
+fn test_sparse_checkout() -> eyre::Result<()> {
+    let git = make_git()?;
+    git.init_repo()?;
+
+    if git.run(&["sparse-checkout", "set"]).is_err() {
+        return Ok(());
+    }
+
+    {
+        let (stdout, _stderr) = git.run(&["config", "extensions.worktreeConfig"])?;
+        insta::assert_snapshot!(stdout, @r###"
+        true
+        "###);
+    }
+
+    if let Ok((stdout, _stderr)) = git.run(&["smartlog"]) {
+        insta::assert_snapshot!(stdout, @"@ f777ecc (> master) create initial.txt
+");
+    } else {
+        let (stdout, _stderr) = git.run_with_options(
+            &["smartlog"],
+            &GitRunOptions {
+                expected_exit_code: 1,
+                ..Default::default()
+            },
+        )?;
+        insta::assert_snapshot!(stdout, @r###"
+        Error: the Git configuration setting `extensions.worktreeConfig` is enabled in
+        this repository. Due to upstream libgit2 limitations, git-branchless does not
+        support repositories with this configuration option enabled.
+
+        Usually, this configuration setting is enabled when initializing a sparse
+        checkout. See https://github.com/arxanas/git-branchless/issues/278 for more
+        information.
+
+        Here are some options:
+
+        - To unset the configuration option, run: git config --unset extensions.worktreeConfig
+          - This is safe unless you created another worktree also using a sparse checkout.
+        - Try upgrading to Git v2.36+ and reinitializing your sparse checkout.
+        "###);
+    }
+
+    Ok(())
+}