Enhance LFS error handling and logging in fetch and push operations

[ardiloot]

This pull request improves Git LFS (Large File Storage) support in pubgate by making LFS object transfers more robust and user-friendly, enhancing manual review workflows for binary/LFS files, and improving logging and error handling. It also introduces better reporting for LFS-tracked files during staging and adds comprehensive tests for LFS fetch/push failures.

LFS object transfer and error handling improvements:

• Changed the timing of git lfs fetch to occur only when needed (before file operations requiring blob content), skipping unnecessary fetches and handling dry-run scenarios. Improved error handling ensures that failures in LFS fetch/push are logged as warnings and do not interrupt workflows. [1] [2]
• Added new tests to verify that LFS fetch/push failures (nonzero exit codes, timeouts, or LFS being unavailable) are handled gracefully and logged appropriately, without raising exceptions.

Manual review and logging enhancements for LFS/binary files:

• Improved the absorb workflow to detect when binary or LFS files differ between branches, logging detailed debug information (including diffs for text files) to aid manual review. The commit message now includes a "Review manually" section listing files that need attention. [1] [2] [3] [4] [5] [6] [7] [8]

Stage snapshot and reporting improvements:

• Modified the stage snapshot function to return both the snapshot and a count of LFS-tracked files. The number of LFS files included in a snapshot is now reported in logs to improve visibility during staging. [1] [2] [3] [4]
• Updated tests to handle the new return value from the snapshot function. [1] [2] [3] [4]

Internal refactoring and startup logic:

• Refactored startup logic to remove redundant LFS fetches, ensuring LFS object fetching is only performed when necessary. [1] [2] [3] [4]

Documentation updates:

• Updated SPEC.md to reflect the new LFS fetch behavior and clarify when LFS operations are performed.