git_workflow.md

Git Workflow & Command Reference

This document governs intentional version control actions for the talkinghead_gen repository.

---

1. Initial Setup & Remote Publishing

• git init: Initialize a new local Git repository.
• git remote add origin <url>: Associate local repo with a remote GitHub repository.
• git branch -M main: Rename current default branch to main.
• git push -u origin main: Push main branch to remote and track upstream.

---

2. Common Workflows

Staging & Status

• git status: Inspect current branch, modified files, and staged changes.
• git diff: Show unstaged modifications.
• git add <file>: Stage specific files for commit.
• git add .: Stage all modified and untracked files.

Commit

• git commit -m "<type>(<scope>): <description>": Record changes with a clear conventional commit message.
  • Types: fix, feat, docs, refactor, style, test, chore.

Synchronization & Deployment

• git fetch origin: Download objects and refs from origin without merging.
• git pull origin main: Fetch and merge changes from remote main.
• git push origin main: Push committed local changes to GitHub main branch. This triggers GitHub Actions CI/CD workflows to automatically deploy the application to Hugging Face Spaces / Google Cloud Run.

---

3. Advanced & Recovery Commands

Use recovery commands with caution as they can alter history or discard local work.

• git stash: Temporarily store uncommitted modifications.
• git stash pop: Restore previously stashed modifications.
• git checkout -b <branch>: Create and switch to a new topic branch.
• git merge <branch>: Merge specified topic branch into current branch.
• git reset --soft HEAD~1: Undo last commit while preserving changes in staging area.
• git reset --hard HEAD~1: DANGER: Discard last commit and all uncommitted working directory changes.
• git revert <commit-hash>: Create a new commit that reverts the changes of specified commit.
• git reflog: View chronological log of reference updates for disaster recovery.

---

4. Execution Justification Policy

Every Git operation executed must be explicitly justified, logged in output_log.md, and aligned with project deployment requirements.