From d4adefc46bc48bffd8079c38373fd8f7e9d30573 Mon Sep 17 00:00:00 2001 From: Shane da Silva Date: Tue, 10 Nov 2026 12:15:51 -0800 Subject: [PATCH] Document missing bundle dependencies during checkout and rebase --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 44ad4d2e..8b0992a2 100644 --- a/README.md +++ b/README.md @@ -363,6 +363,31 @@ significantly reduces the startup delay in your hook runs. It is thus the recommended approach unless your project has a relatively small number of gems in your `Gemfile`. +When using your application's `Gemfile`, a checkout or pull can introduce a +`Gemfile.lock` that requires gems you have not installed yet. Overcommit cannot +load that bundle, so even `post-checkout` hooks fail with a message such as +`Problem loading 'Gemfile': Could not find ...`. The checkout has already changed +your working tree when this happens. During a rebase, a hook error can interrupt +the operation and leave you with a detached HEAD. + +To prevent this, install the updated branch's dependencies before rebasing onto +it, or use the separate hook Gemfile described above so application dependency +updates do not prevent Overcommit from loading. + +If a rebase is interrupted by missing gems: + +1. Run `bundle install --gemfile=Gemfile` (using the path configured in `gemfile`). +2. Run `git status` to check whether a rebase is in progress. If it is, run + `git rebase --abort` to return to your original branch, then retry the rebase. + Restarting also handles a failed commit hook leaving a partly replayed commit. +3. If Git reports no rebase in progress but HEAD is detached, switch back to + your original branch and retry the rebase after installing the updated + branch's dependencies. + +To abandon an in-progress rebase when missing dependencies prevent hooks from +loading, run `OVERCOMMIT_DISABLE=1 git rebase --abort`. This disables Overcommit +for that command. Once dependencies are installed, normal hook runs resume. + ### Plugin Directory You can change the directory that project-specific hooks are loaded from via