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

> [!WARNING]
> 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.