revert-staged.py

revert-staged.py reverts both staged AND unstaged changes for a file back to the last committed version (HEAD).

What It Does

The script:

1. Parses the arguments, so --help and bad arguments never reach git
2. Verifies the file is tracked by git
3. Warns the user about discarding changes
4. Runs git restore --source=HEAD -- <file> to revert the file (the -- makes the path literal, so a name that starts with - or matches a ref is still read as a path)

Usage

python3 scripts/revert-staged.py <file_path>

To restore a file whose name starts with -, put -- before it:

python3 scripts/revert-staged.py -- -notes.txt

Options

• file_path - the file to restore (required, exactly one)
• -h, --help - print the usage text and exit without calling git

Example

python3 scripts/revert-staged.py juneau-core/juneau-marshall/src/main/java/org/apache/juneau/ClassMeta.java

⚠️ Warning

This will discard ALL changes (both staged and unstaged) for the specified file, reverting it back to the last commit.

Exit Codes

• 0 - Success
• 1 - Error (file not tracked, git command failed)
• 2 - Bad arguments (usage text printed to stderr)

Requirements

• Python 3.6 or higher
• Git (git command must be in PATH)
• No external Python dependencies (uses only standard library)

Notes

• The file must be tracked by git (the script verifies this)
• This is a destructive operation - changes cannot be recovered
• Use revert-unstaged.py if you only want to revert unstaged changes while preserving staged changes