How to fix ! [rejected] main -> main (stale info) error: failed to push some refs in Git

### Understanding --force-with-lease

The --force-with-lease flag was added to Git as a safer alternative to --force. It works by checking if your local remote-tracking ref matches the actual remote ref before allowing the push. Think of it as "force push, but only if the remote hasn't changed since I last looked."

The "lease" terminology comes from distributed systems: you're asking for a lease on the remote ref based on your last known state.

### The Fetch-Then-Push Caveat

Be aware that running git fetch immediately before git push --force-with-lease essentially makes it equivalent to git push --force. The safety mechanism relies on your potentially-outdated knowledge of the remote. If you always fetch first, you're always "up to date" from Git's perspective, even if you never actually looked at what was fetched.

### CI/CD Considerations

In CI/CD environments, this error commonly occurs when:

1. Cached Git repositories contain stale refs from previous runs
2. Shallow clones don't have complete ref information
3. Multiple pipeline runs race to push to the same branch

Solutions for CI:

# Always prune before operations
git fetch --prune --unshallow || git fetch --prune

# Or use a fresh clone
git clone --depth 1 <repo>

### Specifying the Expected Ref

For more precise control, you can specify exactly what you expect the remote to look like:

git push --force-with-lease=main:origin/main origin main

This explicitly states your expectation and will fail if the remote doesn't match, regardless of your local tracking branch state.

### Remote Prune Command

You can also manually prune without fetching:

git remote prune origin

This removes stale remote-tracking branches without downloading new objects.