ctx: deprecate git2 boundary and finalize migration doc

Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

Author: codex

crates/but-ctx/src/legacy.rs

@@ -35,6 +35,10 @@ impl Context {
 
     /// Open the repository identified by `legacy_project` and `settings`, while controlling
     /// how the repository sources configuration via `repo_open_mode`.
+    #[allow(
+        deprecated,
+        reason = "Context owns the deprecated boundary cache and must initialize it."
+    )]
     pub fn new_from_legacy_project_and_settings_with_repo_open_mode(
         legacy_project: &gitbutler_project::Project,
         settings: AppSettings,

crates/but-ctx/src/lib.rs

@@ -114,7 +114,10 @@ pub struct Context {
     /// Keep new uses confined to the residual `git2` boundary:
     /// checkout/worktree materialization, staged tree/index materialization,
     /// and deliberate compatibility adapters that still require libgit2.
-    /// Everything else should use [`Self::repo`] instead.
+    /// Activation and read-side flows should use [`Self::repo`] instead.
+    #[deprecated(
+        note = "Boundary-only escape hatch: use Context::repo unless you are crossing the remaining libgit2 checkout/index, hook, or transport/auth adapter boundary."
+    )]
     pub git2_repo: OnDemand<git2::Repository>,
     /// An open handle to the database. It's initialized lazily upon first access.
     /// It is also what makes this type non-Clone, which is fair.
@@ -155,6 +158,10 @@ pub struct ThreadSafeContext {
 }
 
 impl From<ThreadSafeContext> for Context {
+    #[allow(
+        deprecated,
+        reason = "Context owns the deprecated boundary cache and must initialize it."
+    )]
     fn from(value: ThreadSafeContext) -> Self {
         let ThreadSafeContext {
             settings,
@@ -268,6 +275,10 @@ impl Context {
 
     /// Just like [`Context::new()`], but allows controlling how the repository
     /// sources configuration via `repo_open_mode`.
+    #[allow(
+        deprecated,
+        reason = "Context owns the deprecated boundary cache and must initialize it."
+    )]
     pub fn new_with_repo_open_mode(
         gitdir: impl Into<PathBuf>,
         app_config_dir: impl AsRef<Path>,
@@ -373,6 +384,10 @@ impl Context {
         Self::from_repo_with_legacy_support(repo, repo_open_mode)
     }
 
+    #[allow(
+        deprecated,
+        reason = "Context owns the deprecated boundary cache and must initialize it."
+    )]
     fn from_repo_with_legacy_support(
         repo: gix::Repository,
         repo_open_mode: RepoOpenMode,
@@ -433,6 +448,10 @@ impl Context {
     ///
     /// Particularly useful in testing, which might start off with just a Git repository.
     /// **Note that it does not have support for legacy projects to encourage single-branch compatible code.**
+    #[allow(
+        deprecated,
+        reason = "Context owns the deprecated boundary cache and must initialize it."
+    )]
     pub fn from_repo(repo: gix::Repository) -> anyhow::Result<Context> {
         let gitdir = repo.git_dir().to_owned();
         let project_data_dir = repo.gitbutler_storage_path()?;
@@ -959,6 +978,10 @@ impl Context {
     }
 
     /// Take all copyable values and place them in an instance that can pass across thread boundaries.
+    #[allow(
+        deprecated,
+        reason = "Context owns the deprecated boundary cache and must move it out internally."
+    )]
     pub fn into_sync(self) -> ThreadSafeContext {
         let Context {
             settings,

crates/but-testsupport/src/legacy/mod.rs

@@ -34,6 +34,10 @@ pub mod virtual_branches {
     pub fn set_test_target(ctx: &Context) -> anyhow::Result<()> {
         let mut vb_state = VirtualBranchesHandle::new(ctx.project_data_dir());
         let (remote_repo, _tmp) = empty_bare_repository();
+        #[expect(
+            deprecated,
+            reason = "legacy fixture coverage for transport/setup compatibility"
+        )]
         let git2_repo = &*ctx.git2_repo.get()?;
         let mut remote = git2_repo
             .remote("origin", remote_repo.path().to_str().unwrap())

crates/but-workspace/src/legacy/stacks.rs

@@ -498,12 +498,10 @@ pub fn stack_branches(stack_id: StackId, ctx: &Context) -> anyhow::Result<Vec<ui
     let mut current_base = stack.merge_base(ctx)?;
     let repo = ctx.repo.get()?;
     for internal in stack.branches() {
-        let upstream_reference = ctx
-            .git2_repo
-            .get()?
-            .find_reference(&internal.remote_reference(remote.as_str()))
-            .ok()
-            .map(|_| internal.remote_reference(remote.as_str()));
+        let upstream_reference_name = internal.remote_reference(remote.as_str());
+        let upstream_reference = repo
+            .try_find_reference(&upstream_reference_name)?
+            .map(|_| upstream_reference_name);
         let result = ui::Branch {
             name: internal.name().to_owned().into(),
             remote_tracking_branch: upstream_reference.map(Into::into),

crates/gitbutler-branch-actions/src/base.rs

@@ -156,6 +156,7 @@ fn go_back_to_integration(ctx: &Context, default_target: &Target) -> Result<Base
 
         let final_tree_id = outcome.tree.write()?.detach();
 
+        #[expect(deprecated, reason = "checkout/materialization boundary")]
         let git2_repo = &*ctx.git2_repo.get()?;
         let final_tree = git2_repo.find_tree(final_tree_id.to_git2())?;
         git2_repo

crates/gitbutler-branch-actions/src/branch_manager/branch_removal.rs

@@ -35,6 +35,7 @@ impl BranchManager<'_> {
                 .to_string());
         }
 
+        #[expect(deprecated, reason = "checkout/materialization boundary")]
         let git2_repo = self.ctx.git2_repo.get()?;
 
         // Commit any assigned diffspecs if such exist so that it will be part of the unapplied branch.

crates/gitbutler-branch-actions/src/integration.rs

@@ -80,6 +80,7 @@ pub fn update_workspace_commit_with_vb_state(
         .get_default_target()
         .context("failed to get target")?;
 
+    #[expect(deprecated, reason = "workspace checkout/index boundary")]
     let repo = &*ctx.git2_repo.get()?;
     let gix_repo = ctx.repo.get()?.clone();
 
@@ -263,6 +264,7 @@ fn verify_current_branch_name(ctx: &Context) -> Result<&Context> {
 
 // TODO(ST): Probably there should not be an implicit vbranch creation here.
 fn verify_head_is_clean(ctx: &Context, perm: &mut RepoExclusive) -> Result<()> {
+    #[expect(deprecated, reason = "soft reset/index boundary")]
     let git2_repo = &*ctx.git2_repo.get()?;
     let gix_repo = ctx.repo.get()?.clone();
     let head_commit_id = gix_repo.head_id()?.detach();

crates/gitbutler-branch-actions/tests/branch-actions/hooks.rs

@@ -17,6 +17,7 @@ fn post_commit_hook_rejection() -> anyhow::Result<()> {
 echo 'rejected'
 exit 1
 ";
+    #[expect(deprecated, reason = "hook compatibility coverage")]
     git2_hooks::create_hook(&*ctx.git2_repo.get()?, git2_hooks::HOOK_POST_COMMIT, hook);
 
     assert_eq!(
@@ -40,6 +41,7 @@ fn message_hook_rejection() -> anyhow::Result<()> {
 echo 'rejected'
 exit 1
 ";
+    #[expect(deprecated, reason = "hook compatibility coverage")]
     git2_hooks::create_hook(&*ctx.git2_repo.get()?, git2_hooks::HOOK_COMMIT_MSG, hook);
 
     let message = "commit message".to_owned();
@@ -63,6 +65,7 @@ fn rewrite_message() -> anyhow::Result<()> {
 #!/bin/sh
 echo 'rewritten message' > $1
 ";
+    #[expect(deprecated, reason = "hook compatibility coverage")]
     git2_hooks::create_hook(&*ctx.git2_repo.get()?, git2_hooks::HOOK_COMMIT_MSG, hook);
 
     let message = "commit message".to_owned();
@@ -86,6 +89,7 @@ fn keep_message() -> anyhow::Result<()> {
 #!/bin/sh
 echo 'commit message' > $1
 ";
+    #[expect(deprecated, reason = "hook compatibility coverage")]
     git2_hooks::create_hook(&*ctx.git2_repo.get()?, git2_hooks::HOOK_COMMIT_MSG, hook);
 
     let message = "commit message\n".to_owned();
@@ -102,6 +106,7 @@ fn husky_hooks_disabled_even_if_present() -> anyhow::Result<()> {
     let case = suite.new_case();
     let Case { ctx, .. } = &case;
 
+    #[expect(deprecated, reason = "hook compatibility coverage")]
     let repo = ctx.git2_repo.get()?;
     let husky_dir = repo
         .path()

crates/gitbutler-edit-mode/src/lib.rs

@@ -58,6 +58,7 @@ fn get_commit_index(ctx: &Context, commit_id: gix::ObjectId) -> Result<git2::Ind
         }
         gix_to_git2_index(&index)
     } else {
+        #[expect(deprecated, reason = "index materialization boundary")]
         let git2_repo = &*ctx.git2_repo.get()?;
         let commit_tree = git2_repo.find_tree(commit.tree.to_git2())?;
         let mut index = git2::Index::new()?;
@@ -115,6 +116,7 @@ fn get_uncommitted_changes(repo: &gix::Repository) -> Result<gix::ObjectId> {
 
 fn checkout_edit_branch(ctx: &Context, commit_id: gix::ObjectId) -> Result<()> {
     let repo = &*ctx.repo.get()?;
+    #[expect(deprecated, reason = "checkout/index materialization boundary")]
     let git2_repo = &*ctx.git2_repo.get()?;
     let commit = git2_repo.find_commit(commit_id.to_git2())?;
 
@@ -234,6 +236,7 @@ pub(crate) fn abort_and_return_to_workspace(
         );
     }
 
+    #[expect(deprecated, reason = "checkout/materialization boundary")]
     let repo = &*ctx.git2_repo.get()?;
 
     // Checkout gitbutler workspace branch
@@ -253,6 +256,7 @@ pub(crate) fn abort_and_return_to_workspace(
 
 pub(crate) fn save_and_return_to_workspace(ctx: &Context, perm: &mut RepoExclusive) -> Result<()> {
     let edit_mode_metadata = read_edit_mode_metadata(ctx).context("Failed to read metadata")?;
+    #[expect(deprecated, reason = "checkout/index materialization boundary")]
     let git2_repo = &*ctx.git2_repo.get()?;
     let repo = &*ctx.repo.get()?;
 
@@ -360,6 +364,7 @@ pub(crate) fn starting_index_state(
         bail!("Starting index state can only be fetched while in edit mode")
     };
 
+    #[expect(deprecated, reason = "conflicted tree lookup boundary")]
     let git2_repo = &*ctx.git2_repo.get()?;
     let repo = &*ctx.repo.get()?;
 

crates/gitbutler-edit-mode/tests/edit_mode.rs

@@ -227,6 +227,7 @@ fn conficted_entries_get_written_when_leaving_edit_mode() -> Result<()> {
     let stack_id = stack_id(&ctx)?;
     enter_edit_mode(&mut ctx, foobar, stack_id)?;
 
+    #[expect(deprecated, reason = "checkout/index boundary coverage")]
     let repo = ctx.git2_repo.get()?;
     let init = repo.find_reference("refs/heads/main")?.peel_to_commit()?;
     let left = repo.find_reference("refs/heads/left")?.peel_to_commit()?;