The Git Staging Trap: When Your Commit References Code That Doesn’t Exist Yet

You make a change in Client.php that calls a new method getRemainingTtl(). You stage Client.php, write a clean commit message, hit commit. Everything looks fine.

Except getRemainingTtl() lives in AuthSession.php — and you forgot to stage that file.

The Problem

When you selectively stage files with git add, Git doesn’t check whether your staged code actually works together. It just commits whatever’s in the staging area. If File A calls a method defined in File B, and you only stage File A, your commit is broken — even though your working directory is fine.

git add src/Client.php
git commit -m "Add cache TTL awareness to client"
# AuthSession.php with getRemainingTtl() is NOT in this commit

This compiles to a commit where Client.php references a method that doesn’t exist yet. If someone checks out this specific commit — or if CI runs against it — it breaks.

Why It Happens

Selective staging is a good practice. Small, focused commits make history readable. But the trap is that your working directory always has both files, so you never notice the gap. Your editor doesn’t complain. Your local tests pass. Everything works — until it doesn’t.

The Fix: Review the Diff Before Committing

Always check what you’re actually committing:

# See exactly what's staged
git diff --cached

# Or see the file list
git diff --cached --name-only

When you see Client.php calling $this->session->getRemainingTtl(), ask yourself: “Is the file that defines this method also staged?”

A Better Habit

Before committing, scan the staged diff for:

• New method calls — is the definition staged too?
• New imports/use statements — is the imported class staged?
• New interface implementations — is the interface file staged?
• Constructor changes — are the new dependencies staged?

If you catch it before pushing, it’s a 5-second fix: git add AuthSession.php && git commit --amend. If you catch it after CI fails, it’s a new commit plus an embarrassing red build.

Selective staging is powerful, but Git won’t hold your hand. Review the diff, not just the file list.