Git Setup & Workflow

A complete, Windows-focused, step-by-step guide so a new developer can go from zero to a working day-to-day Git workflow on NEFOXX — from cloning the repo through the branch strategy proposed in SonarQube Integration §4c.

1. Prerequisites & installation

• Install Git for Windows. Verify with:

  git --version

• This repo's own tooling already runs through PowerShell and Git Bash (the two shells used throughout the project's own workflow) — either works for day-to-day Git commands.
• VS Code has Git integration built in (Source Control panel) — useful for visual diff/staging, but every operation below also has a plain command-line equivalent, which this guide uses so it works regardless of editor.

2. Global configuration

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

Windows line endings: set core.autocrlf so line endings don't create noisy diffs:

git config --global core.autocrlf true

Set a default editor for commit messages/rebases (optional, defaults to whatever $EDITOR is set to, or a basic built-in editor):

git config --global core.editor "code --wait"

3. Authentication — HTTPS or SSH

Check what this project's remote currently expects:

git remote -v

• If the URL starts with https://github.com/... → HTTPS auth.
• If it starts with git@github.com:... → SSH auth.

HTTPS (Personal Access Token):

1. GitHub → Settings → Developer settings → Personal access tokens → generate a token scoped to repo.
2. The first time you git push/git pull over HTTPS, Windows will prompt for credentials — enter your GitHub username and the token as the password.
3. Windows Credential Manager caches it after that — you won't be prompted again unless the token is revoked/expired.

SSH:

ssh-keygen -t ed25519 -C "you@example.com"

Add the resulting public key (~/.ssh/id_ed25519.pub) to GitHub → Settings → SSH and GPG keys, then verify:

ssh -T git@github.com

A successful response greets you by username — no further password prompts for SSH remotes.

4. Cloning the repo

git clone <repository-url>
cd xtract
git remote -v   # confirm 'origin' points to the correct repo

5. Branching — and the NEFOXX branch strategy

git branch                  # list local branches
git switch -c feature/my-change   # create + switch to a new branch (or: git checkout -b feature/my-change)

NEFOXX branch strategy (per the CI/CD design in SonarQube Integration §4c):

• main — production. Protected. Every deploy to nefoxx.com requires a passing CI Quality Gate and a human-approved GitHub Environment review. Never commit to it directly.
• develop — integration branch. Auto-deploys to devv.nefoxx.com on every push once CI passes. This is where end-to-end testing happens before a production release is planned.
• Feature branches are always cut from develop, never from main:

  git switch develop
  git pull
  git switch -c feature/my-change

6. Staying in sync

git fetch                 # download remote changes without merging
git pull                  # fetch + merge into current branch
git pull --rebase         # fetch + replay your local commits on top (linear history)

Recommendation for this project: use git pull --rebase on your own feature branches to keep history linear and avoid noisy merge commits; a regular merge (or squash-merge via PR) is fine for promoting develop into main.

7. Staging & committing

git status                # see what's changed
git add path/to/file.jsx  # stage a specific file — prefer this over blanket adds
git diff --staged         # review exactly what you're about to commit
git commit -m "Add trade-planner risk summary card"

Avoid git add -A/git add . as a habit — staging files explicitly by name is safer (matches this project's own git-safety guidance): it prevents accidentally committing secrets, generated files, or unrelated in-progress work that happens to sit in the working tree.

Commit message practice:

• Imperative mood ("Add", "Fix", "Refactor" — not "Added"/"Fixes").
• Explain why, not what — the diff already shows what changed.
• Reference the dev tracker NFX-### ID when the commit relates to a tracked item, per CLAUDE.md's tracker policy.

8. Pushing

git push                        # push to the already-tracked remote branch
git push -u origin feature/my-change   # first push of a new local branch — sets up tracking

Force-push is disallowed on develop and main under the branch protection proposed in SonarQube Integration §4c — those branches also require pull requests, so direct or force pushes shouldn't be possible once that protection is configured.

Triggering a CI run without a real code change

ci.yml only fires on an actual push/pull_request, so testing the pipeline itself (a workflow edit, a Cloudflare deploy fix, a Sonar job change) needs a real commit — but not necessarily a real file change. An empty commit does this cleanly, without touching any tracked file:

git commit --allow-empty -m "chore: trigger CI run for pipeline testing"
git push origin develop

Reuse this exact pair whenever you need to re-run build-and-test → sonar-scan → deploy-dev end-to-end (e.g. after changing deploy.yml or a Cloudflare project setting) without inventing a throwaway code comment just to have something to commit.

9. Pull requests

Open a PR from your feature branch into develop (not main). This is what triggers the CI gate described in SonarQube Integration §4b/§4c — lint, tests, build, and the Sonar Quality Gate all run against the PR before it can merge.

Once merged into develop, the change auto-deploys to devv.nefoxx.com. After it's been tested end-to-end there, promotion to production is a separate, deliberate PR/merge from develop into main, gated behind the required-reviewer approval on the production GitHub Environment.

10. Resolving merge conflicts

When a merge or rebase can't auto-resolve, Git marks the conflicting file with markers:

<<<<<<< HEAD
your version
=======
incoming version
>>>>>>> branch-name

1. git status shows which files are still conflicted.
2. Open each file, decide what the final content should be, and remove the <<<<<<</=======/>>>>>>> markers.
3. git add <file> once resolved.
4. Continue the operation: git commit (for a merge) or git rebase --continue (for a rebase).
5. If it's going badly, back out entirely: git merge --abort or git rebase --abort.

11. Keeping branches synchronized

For any feature branch that lives longer than a day or two, regularly bring in the latest develop to avoid a painful conflict later:

git switch feature/my-change
git fetch origin
git rebase origin/develop

12. Verifying remotes

git remote -v                          # confirm origin URL
git branch -vv                         # see each local branch's upstream tracking branch
git log --oneline --graph --all        # visual history across all branches

13. Common day-to-day commands reference

Command	When to use it
git status	Check what's staged/unstaged/untracked before doing anything else.
git log --oneline	Quick scan of recent commit history.
git diff	See unstaged changes.
git stash / git stash pop	Temporarily shelve in-progress work to switch branches, then bring it back.
git restore <file>	Discard unstaged local changes to a file.
git reset --soft HEAD~1	Undo the last local commit but keep the changes staged.
git cherry-pick <commit>	Apply a specific commit from another branch onto the current one.

14. Troubleshooting

• Detached HEAD — you checked out a commit/tag directly instead of a branch. Create a branch from where you are if you want to keep the work: git switch -c recovery-branch.
• Committed to the wrong branch — move the commit: git switch correct-branch, then git cherry-pick <commit-hash>, then remove it from the wrong branch if needed.
• Undo a local-only commit: git reset --soft HEAD~1 (keeps changes) or --hard (discards them — use with care).
• Undo a commit already pushed/shared: don't rewrite shared history — use git revert <commit> instead, which creates a new commit undoing the change.
• Line-ending noise on Windows: confirm core.autocrlf true is set (§2); a one-time git add --renormalize . can clean up an already-affected repo.
• Credential prompts not appearing / stuck on an old token: clear the cached entry in Windows Credential Manager (search "Credential Manager" in Start, remove the git:https://github.com entry) and re-authenticate on the next git push/pull.

15. Recommended workflow summary for NEFOXX

1. Clone the repo, configure user/email/authentication (§1–§4).
2. Branch off develop for any new work (§5).
3. Commit small, meaningful changes with clear messages (§7).
4. Push the branch (§8) and open a PR into develop (§9).
5. CI runs lint/test/build/Sonar Quality Gate on the PR (SonarQube Integration §4b).
6. Merge once green → auto-deploys to devv.nefoxx.com (§4c).
7. Test end-to-end on devv.nefoxx.com.
8. Open a promotion PR from develop into main.
9. A human approves the production GitHub Environment gate.
10. Production deploy ships to nefoxx.com.