Git & Team Workflow

A commit is a snapshot of the whole project plus its parent commits, author and message, named by a hash of all of that. A branch is a movable name pointing at one commit, and HEAD marks what you have checked out, normally a branch. A commit stores the full tree, not a diff, and its hash covers the parents too, so changing an old commit changes every hash after it: that is why rewriting pushed history causes trouble. A branch is just a pointer: a ref in .git/refs/heads/ holding one hash that each new commit moves forward, so creating a branch is instant. **HEAD** normally contains ref: refs/heads/main, so a new commit moves that branch. Detached HEAD: HEAD holds a commit hash directly, after git checkout v1.4.0 or during a rebase or bisect. Commits made there belong to no branch: run git switch -c fix/login before switching away, or find them later in git reflog.

git fetch downloads new commits and moves remote-tracking branches such as origin/main, but never touches your branch or your files. git pull is a fetch followed by a merge (or a rebase) of the upstream branch into the one you are on. Fetch is always safe: run it, then git log main..origin/main to see what arrived before you integrate it. A plain pull merges: when both sides have new commits, you get a "Merge branch 'main' of …" commit that says nothing about the work. **git pull --rebase** replays your unpushed commits on top of the fetched ones and keeps history straight; git config --global pull.rebase true makes it the default. Diverged, with no preference set: current Git stops with fatal: Need to specify how to reconcile divergent branches. until you choose pull.rebase or pull.ff only.

Merge joins two histories with a merge commit and leaves every existing commit as it was. Rebase replays your commits on top of another branch as new commits with new hashes, giving a straight history, which is why rebasing commits others already have breaks their copies. Fast-forward: if main has not moved since you branched, a merge just moves the main label to your last commit; --no-ff forces a merge commit so the feature stays visible as a unit. Merge keeps the true history and is safe on shared branches; the price is a graph full of merge commits. Rebase gives a linear log that is easier to read and to bisect; conflicts come one commit at a time. The golden rule: rebase only commits nobody else has built on. Rebase and force-push a branch a teammate has pulled, and their old commits and your new ones become two copies of the same work.

Open each conflicted file, work out what both sides meant, write the version that keeps both intentions and delete the markers. Then build, run the tests, git add the files and finish with git commit or git rebase --continue; git merge --abort puts everything back if you get lost. See both sides and the base: git status marks conflicted files UU, and git config --global merge.conflictStyle zdiff3 adds the original text between the two sides, so you see what each side changed. Resolve by intent: if one side renamed a method and the other added a call to it, the result needs both. Check before you commit: run the build and the tests, because code that compiles can still be resolved wrong; git diff --check reports any leftover conflict marker. Never commit markers, keep both blocks blindly (two copies of one method or import), take a whole side with --ours or --theirs just to end the conflict, or hand-merge Package.resolved: regenerate it.

git stash shelves your uncommitted changes and leaves a clean working tree; git stash pop brings them back. git cherry-pick <sha> copies the change made by one commit onto the current branch as a new commit with a new hash. git stash New files stay behind: plain git stash saves tracked changes only; git stash -u includes untracked files. Local and easy to forget: stashes are never pushed; name them (git stash push -m "wip: cart badge") and check git stash list. **pop can conflict**: Git then keeps the entry, and you git stash drop it after resolving; for a long detour, a WIP commit is safer. git cherry-pick Typical use: backporting a fix from main to release/1.4; -x records "(cherry picked from commit …)" in the message. The same change twice: the copy has another hash, so a later merge sees two commits, and it conflicts if the code around them changed.

.gitignore only stops untracked files from being added; a file Git already tracks stays tracked whatever the patterns say. Remove it from the index with git rm --cached and commit that: the file stays on your disk but leaves the repository. Patterns are relative to the .gitignore that holds them: /build/ matches at that level only, build/ at any depth, and ! re-includes a path; git check-ignore -v <path> names the line that matched. An iOS project ignores xcuserdata/ (per-user state and private schemes), SwiftPM's .build/, DerivedData/, Pods/ in most teams, fastlane reports and screenshots, and every signing file: .p12, .mobileprovision, AuthKey_*.p8. It commits the .xcodeproj (unless Tuist or XcodeGen generate it), xcshareddata/ with the shared schemes CI builds, Package.resolved and Podfile.lock. **The trap after git rm --cached**: teammates who pull that commit lose their copy of the file, which hurts for a config they filled in by hand, so warn them first.

In project.pbxproj keep both sides' entries, since each added file appears in several sections, then check that it parses and builds. Package.resolved is resolver output: take main's copy and resolve again. Xcode 16 folders or a generated project prevent most of these conflicts. Why it conflicts so often: adding one file writes a PBXFileReference, a PBXBuildFile, a line in its group's children and one in the target's build phase, all in a file the whole team edits. Resolving it: usually both sides added different files, so keep both blocks in every section; the 24-character object ids practically never collide. Where both changed one build setting, choose by intent. Prove it is valid: plutil -lint on the file fails on a leftover marker or a missing brace; then build, because Xcode refuses to open a damaged project. **Not merge=union**: a union driver in .gitattributes also keeps both versions of a changed line, and the damage shows up later. **Package.resolved**: in a merge, git checkout --theirs takes main's (the sides swap in a rebase), then xcodebuild -resolvePackageDependencies or File > Packages > Resolve Package Versions; the diff against main should show only your new pins. Prevention: Xcode 16 buildable folders (PBXFileSystemSynchronizedRootGroup) reference a folder instead of each file, and Convert to Folder migrates an existing group; feature code in local Swift packages keeps file lists out of the project; Tuist or XcodeGen take the project out of git entirely.

A, B and C all move main back to b2 and differ only in where the change from c3 ends up: staged, unstaged or gone. D adds a new commit that undoes c3 and rewrites nothing, so on a pushed branch only git revert is safe. **A, --soft**: the log ends at b2, and git status lists modified: Sources/Networking/APIClient.swift under "Changes to be committed". Handy for squashing recent commits. **B, --mixed**: the log ends at b2, and the same change sits under "Changes not staged for commit". Handy for splitting a commit. **C, --hard**: the log ends at b2 and the tree is clean; only git reflog still knows c3, and uncommitted edits it wipes are lost for good. **D, revert**: the log reads Revert "Add retry", c3, b2, a1; the files match b2, and teammates just pull it. A, B or C on a pushed branch: git status says "Your branch is behind 'origin/main' by 1 commit" and git push is rejected as non-fast-forward; forcing it pulls c3 out from under everyone who has it. **git restore is for files, not history**: git restore <file> drops uncommitted edits, --staged unstages, and --source=b2 <file> brings back one file's old version without moving a branch.

git rebase -i origin/main lists your branch's commits; changing pick to squash, fixup, reword or drop, or reordering lines, rewrites them into a history worth reading. The rewritten branch needs a force push, and --force-with-lease refuses if someone else pushed meanwhile. The verbs: reword edits a message, edit stops so you can amend or split, squash melds into the previous commit and keeps both messages, fixup melds and drops the message, drop deletes the commit. Fixups as you go: git commit --fixup=<sha>, then --autosquash moves each fixup under its target. **--force overwrites blindly: a commit a teammate pushed to the branch an hour ago disappears. --force-with-lease** pushes only if the remote branch is where your last fetch saw it; otherwise ! [rejected] … (stale info). Its gap: an IDE's background fetch updates origin/feature and the lease passes anyway; --force-if-includes (Git 2.30+) also requires the remote tip to be part of your history. Only your own branch: rewriting main or a shared branch breaks the golden rule whatever the flag.

A reset or a rebase does not delete commits, it only stops pointing at them. git reflog lists every position HEAD has had, so you find the hash from before the accident and put a branch back on it with git reset --hard <sha> or git branch rescue <sha>. Read it top down: HEAD@{0} is now; the state you want is the entry just below reset: moving to HEAD~2, or just below the rebase (start) line. Each branch has its own reflog: git reflog show feature/search, where feature/search@{1} is the branch's previous tip. Right after a rebase or a reset: git reset --hard ORIG_HEAD undoes it. Not sure yet? git branch rescue <sha> parks the commit under a name before you look around. What it cannot bring back: edits that were never committed or stashed, because reset --hard overwrites them; staged files survive only as loose objects that git fsck --lost-found may find. Local, and it expires: the reflog is not on the server or in a fresh clone; unreachable entries expire after 30 days by default (the rest after 90), and then git gc may delete the commits.

You mark one commit bad and an older one good, and Git binary-searches the commits between them: it checks out the middle one, you test it and answer good or bad, and the range halves until one commit is left. A thousand commits take about ten steps. Start and finish: git bisect start, git bisect bad, git bisect good v1.4.0; git bisect reset returns you to where you began. **git bisect run <cmd> answers for you: exit code 0 is good, 1 to 127 is bad, and 125 means "cannot test this one, skip it". Write the check first: a test that fails on the bug, left untracked, because checkouts leave untracked files alone. Skip what does not build with exit 125, or bisect blames a commit that merely failed to compile. Old commits, old dependencies**: xcodebuild resolves each commit's own Package.resolved, and a commit that needs a different Xcode from yours is a skip, not a bad. **git bisect start --first-parent** steps only through main's own commits and names the merged pull request that broke it. Flaky tests ruin it: one wrong answer sends the search into the wrong half.

A good message states in a short imperative subject what the commit does and explains in the body why. Conventional Commits add a machine-readable prefix (feat:, fix:, feat!:), so a tool can choose the next semantic version and write the changelog straight from the history. Subject: about 50 characters, imperative ("Add retry to upload", not "Added"), no full stop. After a blank line, a body wrapped at 72 that gives the reason; the diff already shows what changed. One logical change per commit, so it can be reverted or cherry-picked on its own. The format: type(scope): description, with types such as feat, fix, refactor, perf, test, docs, ci and chore. Mapping to semver: fix bumps the patch, feat the minor, and a ! after the type or a BREAKING CHANGE: footer the major. Tools: release-please or semantic-release turn the history into a changelog and a tag. For an app the marketing version is still the product team's call, but the generated notes become the TestFlight and App Store release notes. Squash merges turn the pull request title into the commit on main, so lint PR titles in CI; a commit-msg hook with commitlint catches the rest locally.

A good pull request does one thing, is small enough to read in one sitting, and says why it exists and how it was tested. A good review checks behaviour and design first, leaves formatting to the tools, and marks how much each comment matters. As the author Small and single-purpose: a few hundred changed lines; a refactor, a rename and a feature go in separate pull requests, so each can be reviewed and reverted alone. The description: what and why, how you tested it, what you are unsure about, screenshots or a simulator recording for UI changes, in light and dark mode, and the ticket link. Review your own diff first: stray logs and commented-out code are yours to catch. As the reviewer In this order: does it do what the ticket asks, what breaks (edge cases, errors, concurrency), does it fit the architecture, would a test fail without it; naming and style come last, or from a linter. Label the weight: blocking:, suggestion:, nit:, and approve with comments when only nits remain. Ask rather than order: "What happens here if the request times out?" teaches more than a rewritten snippet. When you disagree Reply to every comment, fixed or with a reason; after two rounds, talk for five minutes or ask the tech lead, and write the decision in the thread.

GitFlow keeps long-lived develop and main branches plus release and hotfix branches, built for scheduled, versioned releases. GitHub flow is short branches off main, merged through a PR and deployed. Trunk-based goes further: branches live a day or two, and unfinished work hides behind flags. GitFlow: feature/* from develop, release/* frozen for testing, hotfix/* from main and merged back into both. Fine for a few big releases a year, heavy otherwise, and develop drifts away from what users run. GitHub flow: every change is a reviewed pull request merged into main and released from there; it needs CI good enough that main is always shippable. Trunk-based: the same with branches measured in hours to days and feature flags for anything not ready; the most merges and the smallest conflicts. Release branches for App Store review: an app cannot be redeployed in minutes, so teams cut release/4.3 from main when the build goes to review, cherry-pick fixes into it with -x, and tag every submitted build (v4.3.0) so a hotfix starts from what users actually have. How to choose: by release cadence and by what a broken release costs; most teams end up with trunk-based plus short-lived release branches.

A pre-commit hook should run fast, self-fixing checks on the staged files only, such as the formatter and a quick lint. CI stays the real gate, because hooks are not cloned with the repository and git commit --no-verify skips them by design. Why a hook enforces nothing: .git/hooks/ is local and never pushed, so a fresh clone has no hooks until someone installs them; a check that must hold lives in CI and in branch protection. Share the setup: commit a lefthook.yml (or a .pre-commit-config.yaml, or a .githooks/ folder plus git config core.hooksPath .githooks) and install it from the project's setup script. What goes in: SwiftFormat and SwiftLint on the staged .swift files; seconds, not minutes, or people start reaching for --no-verify. Re-stage what the hook fixed: a formatter that rewrites files after git add leaves the commit unformatted; lefthook's stage_fixed: true adds them back. What stays out: the build, the test suite and anything that needs a simulator, which belong to CI. Other hooks: commit-msg can check the Conventional Commits format, and pre-push can run the fast unit tests.

Rotate the secret first: revoke it and issue a new one, because it is already in the history and in every clone and fork, and a new commit only hides it from the latest version. Then, if the old value must disappear too, rewrite history with git filter-repo and force-push. The first hour Rotate, then investigate: revoke the App Store Connect API key in App Store Connect, ship the replacement, and check the access logs for use since the push. Why a new commit is not enough: every old commit still contains the value, bots scan public pushes within minutes, and in a private repository every person, CI runner and integration with read access has a copy. Cleaning the history Rewrite: in a fresh clone, git filter-repo --sensitive-data-removal --invert-paths --path fastlane/AuthKey_ABC123XYZ9.p8 drops the file from every commit (--replace-text replaces a string instead), and git push --force --mirror origin overwrites the server; branch protection has to allow it for the moment. What it costs: every later hash changes, open pull requests break, and teammates must re-clone, since one push from an old clone brings the secret back. On GitHub: pull request refs and cached views keep the old commits until GitHub Support removes them, and forks keep their own copies. Next time Keys and certificates live in the CI secret store, the Keychain or fastlane match's encrypted repository, and build-time values in a gitignored .xcconfig; a committed example file lists the names without values. A secret scanner (gitleaks, trufflehog) in the pre-commit hook and in CI, plus the host's push protection, stops the next one before it lands.

A revert undoes the changes but not the history: main still contains PR #42's two commits, so the second merge brings in only what is new on the branch, the one fix. To get the feature back, revert the revert (git revert <revert-sha>) and then merge the fix. What Git sees: the merge base of main and the branch is now the branch's old tip, already part of main. From there the branch changed one file, so the merge applies one change on top of a main where the revert removed everything else. The output gives it away: Merge made by the 'ort' strategy. followed by Sources/Cart/Cart.swift | 1 + for a feature of two commits. The fix: revert the revert commit, which Git names Reapply "Merge PR #42: discounts", then merge the branch; on GitHub, the Revert button on the revert's pull request does the same. If the fix touches code the feature added, the merge stops with a conflict (CONFLICT (modify/delete) when the file was new), which is at least loud. **-m 1**: a merge commit has two parents, and -m 1 tells revert to keep main's side, almost always what you mean. Revert is still the right tool: on a shared main it is the only undo that rewrites nothing. The trap is forgetting that the undo is now part of the history, so write the plan in the revert's pull request.

Choose a monorepo when the code changes together: apps sharing a design system, an API client and models, where one pull request should update a library and every caller at once. Separate repositories suit parts with their own owners and release cycles, at the cost of versioning between them. What a monorepo gives Atomic changes: a breaking change in a shared package and its fix in every app land in one reviewed pull request; no matrix of "app 2 still uses core 1.4". One toolchain, one set of rules: one Xcode version, one SwiftLint config, and local Swift packages referenced by path instead of by version. What it costs CI must build only what changed, or every pull request runs everything: map the changed paths (git diff --name-only origin/main...) to the packages and test plans they affect. Ownership: CODEOWNERS per folder, so the payments team reviews payments code. Scale and access: the clone keeps growing (git clone --filter=blob:none and sparse checkout help), and access is per repository, so a contractor sees everything. Independent releases get harder: each package needs its own tags (core-v1.4.0) and publishing tooling. What separate repositories cost Every shared change is a publish, a version bump and a pull request in each consumer, and consumers drift versions apart. They win for open-source packages, for code with a different access level, and for teams that really ship on their own schedule.