Tags: code

This workflow assists you in several ways. It provides comprehensive tracking of every version of your script, ensuring that all changes are documented and easily accessible. Additionally, it offers secure testing and experimentation, allowing you to explore new ideas with confidence. If needed, you can effortlessly revert to a known good state at any time, ensuring the reliability and stability of your work.

Step 1: Initialize Git (Once Per Project)

cd your-project-folder
git init
git add .
git commit -m "Initial commit: working build.py"

Step 2: Commit Changes as You Revise

Before making a change to build.py, stay on the main branch:

git checkout main

After every meaningful change:

git add build.py
git commit -m "Describe the change"

Examples:

git commit -m "Add HTML boilerplate to index.html"
git commit -m "Fix repeated references issue"

Step 3: Test Safely Using Branches (Optional but Recommended)

Before risky edits:

git checkout -b test-citations

Work on your changes. If successful:

git checkout main
git merge test-citations

If not:

git checkout main
git branch -D test-citations

Step 4: Find and Revert to a Previous Working Version

A. View the commit history:

git log --oneline

Example output:

e81fa4d Fix broken citation rendering
c44b6a1 Add dark mode support in CSS
d12e3c2 Initial working version

B. Revert just the file (safe revert):

git checkout d12e3c2 -- build.py
git commit -m "Revert build.py to earlier version"

C. Or check out an older version temporarily:

git checkout d12e3c2

Return to latest:

git checkout main

Step 5: Clean Up and Ignore Generated Files

To avoid clutter in Git, create a .gitignore file:

.gitignore contents:

*.tmp.md
fragments/
*.html

Then commit:

git add .gitignore
git commit -m "Ignore temp and generated files"

Helpful Commands

• Check changes: git status
• See commit history: git log –oneline
• Undo uncommitted changes: git restore build.py
• Undo last commit (carefully!): git reset –soft HEAD~1

Git Workflow Summary

1. Initialize Git in Your Project Directory

git init

Creates a Git repository in your current folder.

2. Commit A Working Version of the Script

After verifying the script works:

git add build.py
git commit -m "Working: generates single-page index.html with per-fragment refs"

3. Make Changes and Test

Edit build.py as needed.

If it works:

git add build.py
git commit -m "Added metadata parsing and citation support"

If it breaks: - Revert to last known working state (see Step 4)

4. Revert To a Previous Version

List commits:

git log --oneline

Restore build.py to a known commit:

git checkout <commit-id> -- build.py

Or reset entire project:

git reset --hard <commit-id>

5. Optional: Create a Backup Branch Before Risky Edits

git checkout -b backup-before-big-change

Make changes on a new branch. If it fails, you can return to main:

git checkout main

A Website Repo where You don’t Want History

git add -A && git commit --amend -m "Update site" && git push -f

What this does:

1. git add -A → stage all changes (new, modified, deleted files).
2. git commit –amend -m “Update site” → replace the previous commit with a new one (same spot in history).
3. git push -f → force push to GitHub, overwriting the remote commit.