# ScapeTime Developer Git Workflow Last updated: 2026-03-28 --- ## Branch Directory ### Permanent / Infrastructure | Branch | Purpose | Merges to main? | |--------|---------|----------------| | `main` | Gold standard — always byte-exact with live production (scapetime.net). Every file in main matches live exactly (line endings, encoding, content). | Never directly — only via feature branch merge | | `environment-all` | Files that exist on live but are NOT tracked in main: `.htaccess`, `index.php`, `files/`, `trainingfiles/`, `ckeditor/`, `ckeditor5/`, `ckfinder/`, `google/`, `libchart/`, `fpdf_merge.php`, and other env-layer items. Applied on top of main at deploy/setup time. | Never | | `environment-php8` | PHP 8 compatible libraries: `system/`, `modules/`, `tcpdf-main/`, `fpdf2/`, `fpdi2/`, `PDFMerger/`. Applied on PHP 8 servers. | Never | | `environment-php5` | PHP 5 compatible libraries: same lib set, older versions. Applied on PHP 5 servers. Legacy reference only. | Never | | `environment-xampp` | Windows dev machine config for st.test: Apache vhosts, mkcert SSL certs + CA root, hosts file entries. Apply once on a new dev machine — see `xampp-config/SETUP.md`. | Never | | `environment-training` | Static training content deployed by the dev team: `training/` (audio, PDFs, newsletters), `videos/`, `documentation/`. Grows as new content is added. `training/workers.mp4` (135MB) is server-only — documented in `training/SERVER-ONLY-FILES.md`. | Never | | `svn-repo` | Last SVN snapshot before Git migration. Reference only — never merge. | Never | | `live-snapshot` | Point-in-time capture of live server at migration. Reference only. | Never | | `live-parity` | Used during parity reconciliation work. Reference only. | Never | | `live-reconcile` | Used during SVN-to-Git reconciliation. Reference only. | Never | ### Active Feature Branches | Branch | Purpose | Merges to main? | |--------|---------|----------------| | `workorder-notifications` | WO notification system (crew missed, call customer tabs). Merged to main — keep until confirmed stable on live. | Done | | `property-brochure` | Digital signature flow for project brochure proposals. | Yes, when released | | `property-budgeting` | Property budget management features. | Yes, when released | | `proposal-analysis-v2` | Proposal analysis enhancements v2. | Yes, when released | | `dial` | Dialer / call management feature. | Yes, when released | | `dial-clean` | Clean/rebased version of dial branch. | Yes, when released | | `dial-odd-things` | Dial edge cases and experimental work. | Yes, when released | | `irrigation` | Irrigation module work. | Yes, when released | | `irrigation-tablet-repair-flow` | Tablet-optimized irrigation repair flow. | Yes, when released | | `inspection` | Property inspection module. | Yes, when released | | `lighting-trees` | Lighting and trees service module. | Yes, when released | | `procurement` | Procurement / purchasing module. | Yes, when released | | `acctmgranalytics` | Account manager analytics and reporting. | Yes, when released | | `adp` | ADP payroll integration. | Yes, when released | | `agenda` | Agenda / scheduling feature. | Yes, when released | | `employees-prototype` | Employee management prototype. | Yes, when released | | `goals-pts` | Goals and points system. | Yes, when released | | `modules` | Multi-module work. | Yes, when released | | `backend` | Backend / admin work. | Yes, when released | | `misc` | Miscellaneous small changes not tied to a specific feature. | Yes, when ready | | `enh-statereport-and-pipeline` | State report and pipeline enhancements. | Yes, when released | | `domain-detection-updates` | Domain detection logic updates. | Yes, when released | | `view-update-diffs` | View layer updates and diff tracking. | Yes, when released | | `feature/meeting-stt` | Meeting speech-to-text feature. | Yes, when released | --- ## New Dev Platform Setup ### Prerequisites Install these before starting: - **Windows 11** + **WSL2** (Ubuntu) - **VS Code** with WSL extension - **Git for Windows** - **XAMPP** at `C:\xampp` (PHP 8.x + Apache — do NOT use the XAMPP MySQL, use standalone PostgreSQL) - **PostgreSQL for Windows** — configured to listen on all interfaces (needed for WSL access) - **WinSCP** at `C:\Program Files (x86)\WinSCP\` — used by the `/parity-check` skill - **mkcert** — for local HTTPS certificates (see SSL setup below) - **NuSphere PhpED** — set file encoding to **UTF-8 (no BOM)** before editing any files --- ### Step 1 — Checkout environment-xampp for config files The `environment-xampp` branch contains all the Windows config files you need. Check it out into a temp location to copy from: ```bash git fetch origin git checkout origin/environment-xampp -- xampp-config/ ``` Then follow `xampp-config/SETUP.md` for the full walkthrough. Steps 2-4 below summarize what it covers. --- ### Step 2 — SSL certificates with mkcert mkcert generates locally-trusted HTTPS certificates. The `.pem` files are signed by a local CA that mkcert installs into the Windows trust store. **These certs cannot be copied from another machine** — you must generate them fresh on each dev machine. **Install mkcert** (run in PowerShell as Administrator): ```powershell # Option 1: via Chocolatey choco install mkcert # Option 2: via Scoop scoop install mkcert # Option 3: manual — download mkcert.exe from https://github.com/FiloSottile/mkcert/releases # Place mkcert.exe in C:\Windows\System32\ or add to PATH ``` **Install the local CA** (run once per machine, as Administrator): ```powershell mkcert -install ``` This installs the CA into Windows Certificate Store and Firefox (if installed). Browsers on this machine will now trust any cert mkcert generates. **Generate the st.test certificate:** ```powershell cd C:\xampp\apache\conf\ssl mkcert st.test "*.st.test" ``` This creates two files: - `st.test+1.pem` — the certificate - `st.test+1-key.pem` — the private key These are referenced by the HTTPS vhost (see Step 3). --- ### Step 3 — Apache vhost configuration Edit `C:\xampp\apache\conf\extra\httpd-vhosts.conf` and add the following two blocks for `st.test`. Only these blocks are needed for ScapeTime dev work: ```apache # st.test — HTTP ServerName st.test ServerAlias *.st.test DocumentRoot "c:/webdocs/scapetime_2026" AllowOverride All Require all granted # st.test — HTTPS ServerName st.test ServerAlias *.st.test DocumentRoot "c:/webdocs/scapetime_2026" SSLEngine on SSLCertificateFile "C:/xampp/apache/conf/ssl/st.test+1.pem" SSLCertificateKeyFile "C:/xampp/apache/conf/ssl/st.test+1-key.pem" AllowOverride All Require all granted ``` Ensure `httpd-ssl.conf` is included in `httpd.conf`: ```apache Include conf/extra/httpd-ssl.conf Include conf/extra/httpd-vhosts.conf ``` And that these modules are enabled in `httpd.conf` (uncomment if needed): ```apache LoadModule ssl_module modules/mod_ssl.so LoadModule rewrite_module modules/mod_rewrite.so LoadModule vhost_alias_module modules/mod_vhost_alias.so ``` --- ### Step 4 — Clone the repo In WSL: ```bash cd /mnt/c/webdocs git clone https://ericLUSA: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@github.com/ChrisLUSA/scapetime.git scapetime_2026 cd scapetime_2026 ``` --- ### Step 5 — Apply environment layers on top of main ```bash git checkout main git checkout origin/environment-php8 -- . git checkout origin/environment-all -- . git restore --staged . ``` This places all environment files (PHP libs, `.htaccess`, `index.php`, `ckeditor/`, etc.) on disk without marking them as staged changes. They are gitignored from main and will survive branch switches. --- ### Step 6 — Configure database.php Edit `modules/database/config/database.php`: - WSL to Windows PostgreSQL: host = `192.168.x.x` (find your WSL gateway with `ip route | grep default`) - Native Windows PHP: host = `localhost` Set the database name, user, and password to match your local PostgreSQL instance. --- ### Step 7 — Create required runtime directories These are gitignored and must be created manually: ```bash mkdir -p application/logs application/cache sandbox/cache/proposaljobcost ``` --- ### Step 8 — Restore the database Restore a production dump into your local PostgreSQL instance. Ask the team for the latest dump file. ```bash pg_restore -U postgres -d scapetime /path/to/dump.dump ``` --- ### Step 9 — Verify Restart Apache and hit `https://st.test` — should load with a valid (green padlock) HTTPS connection and no PHP errors. --- ## Day-to-Day Workflow ### Starting new work Use the `/branch` skill or do it manually: ```bash # Skill shortcut: /branch feature/my-thing # Manual: git checkout main git pull origin main git checkout -b feature/my-thing ``` If you're mid-work on another branch and don't want to lose context, `/branch` will offer to create a **worktree** instead — a second checkout of the repo where you can work on the new branch without touching your current one. ### Working on a branch ```bash # make changes, test on https://st.test git add # never git add -A /commit # checks @debug, formats message git push -u origin feature/my-thing ``` ### Creating a pull request Use the `/pr` skill or do it manually: ```bash # Skill shortcut (auto-generates title, assigns Eric as reviewer): /pr # Manual: gh pr create --base main --reviewer ericLUSA --title "My thing" --body "description" ``` ### Reviewing a PR To review Eric's PR without leaving your current branch, use a worktree: ```bash /worktree pr 5 # checks out PR #5 into a worktree # review the code in VS Code at /mnt/c/webdocs/scapetime-worktrees// /worktree remove # clean up when done ``` ### Merging **Squash merge on GitHub** is the default. Click "Squash and merge" on the PR page. This compresses all branch commits into one clean commit on main. Use regular merge only when the individual commits tell a meaningful story worth preserving. ### After merge — sync locally Use the `/sync` skill or do it manually: ```bash # Skill shortcut (pulls main, deletes merged branches + worktrees): /sync # Manual: git checkout main git pull origin main git fetch --prune git branch -d feature/my-thing ``` ### Deploying to live Copy changed files to live via NuSphere (paste from main). After deploy, run: ``` /diff-live ``` to confirm full parity across all tracked folders. ### Context-switching **Use worktrees, not `git stash`.** Worktrees let you have multiple branches checked out at the same time in separate directories. ```bash /worktree list # see all active worktrees /worktree feature/dial # create a worktree for an existing branch /worktree remove feature/dial # clean up when done ``` All worktrees live in `/mnt/c/webdocs/scapetime-worktrees//`. They share the same git history, branches, and remotes as the main repo — just a different directory with a different branch checked out. ### Local merge (emergency only) If GitHub is down or it's a time-critical hotfix, you can merge locally: ```bash git checkout main git pull origin main git merge feature/hotfix git push origin main git branch -d feature/hotfix ``` Create a PR after the fact if possible, for the record. ### Rebuilding st.test from main ``` /build-sttest ``` ### Switching st.test back to dev working copy ``` /build-dev ``` --- ## Environment File Contamination — What It Is and How to Avoid It This is the most common mistake on a new dev machine. It results in feature branches that are hundreds of files larger than they should be, and makes code review and merging very difficult. ### What happens When you clone the repo and apply the environment overlays (`environment-php8`, `environment-all`), files like `.htaccess`, `index.php`, `PHPMailer/`, `ckeditor/`, `system/`, `modules/`, etc. land in your working directory. These files are gitignored from `main` and all feature branches — they should never appear in a commit. However, `git status` will NOT show them as untracked (because they are gitignored). The problem comes when you run `git add -A` or `git add .` — in some cases git can pick them up, or if you are on a branch where the gitignore was misconfigured at the time of branching, they will appear as staged. The result: your feature branch contains PHPMailer, .htaccess, ckeditor, and hundreds of other environment files that have nothing to do with your work. ### How to check if your branch is contaminated ```bash git diff main origin/your-branch --name-only | grep -v "^application/" | grep -v "^images/" | grep -v "^css/" | grep -v "^scripts/" | grep -v "^project/" ``` If you see `.htaccess`, `PHPMailer/`, `system/`, `modules/`, `ckeditor/`, `index.php` — your branch is contaminated. ### How to fix it Never use `git add -A` or `git add .`. Always stage specific files: ```bash git add application/classes/Controller/MyController.php git add application/views/myfeature/v_myview.php ``` If your branch is already contaminated, unstage everything and re-add only your actual changed files: ```bash git restore --staged . git add ``` If environment files have already been committed to your branch, you need to remove them from the branch history or at minimum remove them before merging to main. Ask Eric before attempting this. ### The safe workflow ```bash git checkout main git pull origin main git checkout -b my-feature # Make your changes — only touch files relevant to your feature # Stage ONLY those files by name git add application/classes/Controller/MyController.php # Verify what you're about to commit git diff --cached --name-only # Commit git commit -m "my-feature: description of change" ``` `git diff --cached --name-only` before every commit is your safety check. If you see anything outside `application/`, `images/`, `css/`, `scripts/`, or `project/` — stop and investigate before committing. --- ## Key Rules - **main = live at all times.** If you hotfix directly on live, sync main immediately. - **Pull requests for all changes.** Push branch → PR → squash merge. Local merge only for emergencies. - **Squash merge by default.** Keeps main history clean — one commit per feature/fix. - **Worktrees over stashing.** Use `/worktree` to context-switch, never `git stash`. - **Default reviewer: ericLUSA.** Every PR gets a review, even on a two-person team. - **CRLF standard.** All files in main use CRLF line endings. Live becomes CRLF naturally as files are deployed. - **UTF-8 encoding.** All files must be UTF-8. NuSphere must be set to UTF-8 (no BOM) or non-ASCII characters will corrupt on copy-paste. - **Never merge environment branches into main.** They are overlaid at deploy time, not merged. - **No @debug in commits.** The `/commit` skill blocks `// @debug`, `DebugBreak()`, and `xdebug_break()` — resolve before committing. - **One feature per branch.** Keep features isolated so they can be released independently. - **Test on st.test before creating a PR.** - **Commit specific files** — avoid `git add -A` to prevent accidentally staging environment files or sensitive config. - **Delete branches after merge.** `/sync` handles this automatically. - **mkcert certs are machine-specific.** Never copy `.pem` files between machines — always regenerate with `mkcert st.test "*.st.test"` on each new machine. --- ## Appendix A — Shared Claude Skills (Future) Claude Code skills (slash commands like `/use-branch`, `/parity-check`, `/commit`) are stored in `.claude/commands/` on each developer's machine. Currently each developer maintains their own local copy. **Planned shared skill setup:** Skills will be stored on a shared NAS drive mapped to the same drive letter on all dev machines (e.g. `Z:`). Each developer's global `CLAUDE.md` will instruct Claude to load shared skills from `Z:\.claude\commands\` in addition to their local commands. When a skill is updated in the shared location, all developers get it immediately without a git pull. Until that is set up: when a new shared skill is created or updated, it will be distributed manually. Check with Eric for the latest versions of: - `/use-branch` — checkout a branch and restore all operational files (env-php8, env-all overlays, runtime dirs) - `/parity-check` — compare main against live server via SSH md5sum - `/commit` — stage and commit with @debug check **Why this matters:** Using outdated skill versions — especially `/use-branch` — is the most common cause of environment file contamination in commits. Always use the current skill before starting work on a branch.