Git Workflow for Team Collaboration

This guide explains how to work with this repository when multiple team members are editing documentation using Cursor or other editors.

Repository Setup

• Repository: Pacing-Agency/techstackdocs (private GitHub repo)
• Default branch: main
• Deployment: Automatic via Cloudflare Pages on push to main
• Workspace location: Google Drive shared folder (synced locally)
• Multi-user: Yes, multiple team members can work in the same folder

First-Time Setup

1. Clone the Repository

git clone git@github.com:Pacing-Agency/techstackdocs.git
cd techstackdocs

2. Configure Git (if not already done)

git config user.name "Your Name"
git config user.email "your.email@example.com"

3. Verify Remote

git remote -v
# Should show:
# origin  git@github.com:Pacing-Agency/techstackdocs.git (fetch)
# origin  git@github.com:Pacing-Agency/techstackdocs.git (push)

Daily Workflow: Making Edits

Step 1: Start Fresh (Always)

Before making any edits, pull the latest changes:

git pull origin main

This ensures you're working with the most recent version and reduces merge conflicts.

Step 2: Make Your Edits

Edit files directly in your editor (Cursor, VS Code, etc.):

• tools/<tool-name>.md - Tool documentation
• architecture.md - Architecture overview
• README.md - Main README
• scripts/resources/<tool-name>/ - Scripts and resources

Important:

• Edit source files in the root directory, not generated files in docusaurus/docs/tools/
• The Docusaurus site auto-syncs on build, so you don't need to touch docusaurus/ files

Step 3: Review Your Changes

git status          # See what files changed
git diff           # See the actual changes (optional)

Step 4: Commit Your Changes

git add <file1> <file2> ...    # Add specific files
# OR
git add .                      # Add all changes

git commit -m "Brief description of changes"

Good commit messages:

• "Update webflow.md with new CMS collection IDs"
• "Add n8n workflow documentation for Twilio"
• "Fix typo in architecture.md"

Step 5: Push to GitHub

git push origin main

That's it! Cloudflare Pages will automatically:

1. Detect the push
2. Run the sync script
3. Build the Docusaurus site
4. Deploy to https://docs.pacing.agency (protected by Cloudflare Access)

Handling Conflicts (When Multiple People Edit)

Scenario: Someone Else Pushed Before You

If you try to push and get an error:

! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'origin'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.

Solution:

1. Pull the latest changes:

   git pull origin main

2. Git will attempt to auto-merge. If successful:

   • Review the merged changes
   • Push: git push origin main

3. If there are conflicts (Git can't auto-merge):

   • Git will mark conflicted files
   • Open the files in your editor
   • Look for conflict markers:

     <<<<<<< HEAD
     Your changes
     =======
     Their changes
     >>>>>>> branch-name

   • Manually resolve by keeping both changes or choosing one
   • Remove the conflict markers
   • Save the file

4. After resolving conflicts:

   git add <resolved-file>
   git commit -m "Resolve merge conflict in <file>"
   git push origin main

Best Practices for Team Collaboration

1. Pull Before Starting Work

Always start your session with:

git pull origin main

This prevents most conflicts.

2. Work on Different Files When Possible

• If editing tools, try to work on different tools/*.md files
• If you must edit the same file, coordinate or work sequentially

3. Keep Commits Focused

• One logical change per commit
• Don't mix unrelated changes (e.g., don't update 5 different tools in one commit unless they're related)

4. Commit Frequently

• Don't wait until the end of the day
• Commit after completing a logical unit of work
• This makes conflicts smaller and easier to resolve

5. Communicate Big Changes

• If you're making major changes to architecture.md or README.md, let the team know
• Consider using a branch for large refactors (see "Advanced: Using Branches" below)

Advanced: Using Branches (Optional)

For larger changes or experiments, you can use branches:

Create a Branch

git checkout -b feature/my-feature-name
# Make your changes
git add .
git commit -m "Description"
git push origin feature/my-feature-name

Merge Back to Main

1. Create a Pull Request on GitHub (recommended for review)
2. Or merge locally:

   git checkout main
   git pull origin main
   git merge feature/my-feature-name
   git push origin main

Verifying Your Changes

Check Local Changes

git status        # What files changed
git diff          # See actual changes
git log --oneline # Recent commits

Check Remote Status

git fetch origin
git status        # Shows if you're ahead/behind remote

View Site After Push

1. Wait 2-3 minutes for Cloudflare Pages to build
2. Visit https://docs.pacing.agency (requires Google OAuth login)
3. Check the "Tools" section for your new/updated docs

Troubleshooting

"Your branch is ahead of 'origin/main'"

This means you have local commits not yet pushed:

git push origin main

"Your branch is behind 'origin/main'"

This means remote has changes you don't have:

git pull origin main

"You have uncommitted changes"

You have edited files but haven't committed:

git add .
git commit -m "Your message"
git push origin main

Accidentally Edited Generated Files

If you edited docusaurus/docs/tools/*.md (generated files):

git checkout docusaurus/docs/tools/
# Then edit the source file in tools/ instead

Undo Last Commit (Before Pushing)

git reset --soft HEAD~1  # Keeps changes, removes commit
# OR
git reset --hard HEAD~1  # Removes changes and commit (careful!)

Undo Last Commit (After Pushing)

Don't do this if others have pulled your changes! Instead, make a new commit that fixes it.

If you must:

git revert HEAD
git push origin main

Quick Reference

Task	Command
Get latest changes	git pull origin main
See what changed	git status
See actual changes	git diff
Stage changes	git add <file> or git add .
Commit	git commit -m "message"
Push	git push origin main
View recent commits	git log --oneline
Check remote status	git fetch origin && git status

Summary

Daily workflow:

1. git pull origin main (start fresh)
2. Make your edits
3. git add .
4. git commit -m "description"
5. git push origin main
6. Wait 2-3 minutes, check https://docs.pacing.agency (requires Google OAuth login)

If conflicts occur:

1. git pull origin main
2. Resolve conflicts in your editor
3. git add <resolved-files>
4. git commit -m "Resolve conflicts"
5. git push origin main

That's it! The key is: always pull before you start, and push when you're done.