Laravel Git Blog

A First CI Pipeline for a Laravel Project

Wed, 21 Oct 2026 00:00:00 GMT

CI does not need to be elaborate to be valuable. For a small Laravel team, a first pipeline is four jobs that run on every pull request, and its real product is a green checkmark everyone trusts.

The four jobs

Install: composer install and npm ci. If dependencies cannot install cleanly from the lockfiles, nothing else matters - this is why the lockfiles are committed.
Lint: ./vendor/bin/pint --test fails the build on style drift, so style stops being a code review topic.
Test: php artisan test against a throwaway database (SQLite in memory is enough for a first pipeline).
Build: npm run build proves the frontend compiles - the failure you do not want to meet at deploy time.

Any pipeline runner can express this: GitHub Actions, GitLab CI, or the CI your self-hosted setup provides. The shape is the same everywhere: checkout, cache the composer/npm directories, run the four jobs.

Make the check required

A pipeline nobody is forced to wait for becomes decoration within a month. Wire it into branch protection: pull requests cannot merge until CI is green. That single setting is the difference between "we have CI" and "CI has us" - and it is what lets small PRs move quickly, because reviewers see the robot's verdict before they spend their own attention.

Keep it boring and fast

Two traps make teams abandon CI:

Slow runs. Cache dependencies, and resist running the full browser-test suite on every push - that belongs in a nightly job. A PR pipeline that answers in under five minutes gets respected; one that takes forty gets bypassed.
Flaky tests. A test that fails randomly teaches everyone to click "re-run" without looking, which is worse than no test. Quarantine flakes the week they appear.

What not to automate yet

Deploys. The first pipeline stops at the green checkmark on the PR; deployment stays a deliberate human act until the test suite earns more trust. When that day comes, the pipeline's final job is a tag, and Deploy With Tags, Not Branches takes it from there.

Four jobs, one required check, five minutes. That is the whole first pipeline - everything after is refinement.

A Staging Environment Worth Having

Wed, 21 Oct 2026 00:00:00 GMT

Most staging environments fail quietly: they run different code, on different data, deployed by a different process, so a green staging test proves almost nothing and everyone learns to ignore it. A staging environment earns its cost by being production's rehearsal room, and that property comes from three decisions.

Same deploy path

Deploy to staging exactly the way you deploy to production - same script, same releases and symlink structure, same tag-based flow, differing only in target host. This is the highest-value property: most deploy failures are process failures, and you want to meet them on staging. If production deploys a tag and staging deploys "whatever branch someone pushed," staging is testing a process you do not use.

Same shape of services

Match the services that change behavior: same PHP version, same database engine and version, a real queue worker, a real cache. SQLite on staging against MySQL in production hides the query that only MySQL rejects. The hardware can be smaller - the interfaces cannot.

Sanitized, realistic data

Copy production data down and scrub it: anonymize emails, strip tokens and personal fields, keep the volumes and shapes. User::factory() data has perfect distributions and no history; real data has a user from 2019 with a null middle name that breaks your new export. Laravel's model factories can help fill gaps, but the scrubbed copy is what finds migration surprises.

What staging is for

Decide, write it down, and the environment stays healthy:

Rehearse deploys and migrations before production.
Let someone click through a feature before release.
Reproduce a production bug without touching production.

What it is not: a long-lived fork of production with its own data edits, or a second production for selected users. Both drift, and drifted staging is worse than none - it provides false confidence.

The env file for staging points at its own services but mirrors production's key list, and the quarterly audit keeps it that way. Done right, "it worked on staging" is a sentence worth saying in an incident review.

Annotating Commits with git notes: Metadata Without Rewriting History

Wed, 21 Oct 2026 00:00:00 GMT

Every so often a commit needs a footnote. The reviewer found something worth remembering. The ticket reference went missing. A benchmark run proved the change was worth it. The message is already written and pushed, though - and rewriting pushed history is a bad trade for a footnote.

git notes is the feature for exactly this: annotations that attach to a commit without changing the commit.

The basics

git notes add -m "Reviewed in PR #412, follow-up filed as BILL-88" HEAD
git log --show-notes

The note shows up in git log output under the commit message. The commit hash does not change - the note lives in a separate ref (refs/notes/commits), so nothing is rewritten and nobody else's clone breaks.

Notes do not push by default, which surprises everyone once:

git push origin refs/notes/commits
git fetch origin refs/notes/commits:refs/notes/commits

Share them by pushing the notes ref; teammates fetch it explicitly. It is one extra step, once, per clone.

What Laravel teams actually use them for

Linking commits to review. A note with the pull request URL makes git blame and history archaeology richer months later, without touching the original message.
Recording verification. "Deployed to staging 2026-10-20, smoke tests green" - evidence attached to the exact commit it concerns.
Explaining the weird one. The commit that looks wrong but is deliberate gets a note saying why, so the next person does not "fix" it.

The honest limits

Notes are the right size for footnotes, not documentation. They are easy to forget (out of git log unless you ask), awkward to merge when two people annotate the same commit, and invisible on most web UIs - GitHub shows them in the API but not prominently in the interface. If the information matters to everyone every day, put it in the commit message or the changelog instead.

Reach for notes when the annotation is valuable to the future archaeologist and not worth a history rewrite: that is a real niche, and nothing else in Git fills it as cleanly.

Backing Up Your Git Server So It Actually Restores

Wed, 21 Oct 2026 00:00:00 GMT

Self-hosting your Git means the server is the canonical copy. Developers' clones soften the blow of losing it - every clone has the history - but a clone is not a backup of the server: hooks, server config, access rules and anything outside the refs live nowhere else. A backup plan has to cover both, and it only counts if a restore has been rehearsed.

Mirror the repositories

git clone --mirror git@yourserver:app.git

A mirror clone copies every ref - branches, tags, notes - and none of the working-tree state. To refresh it:

git -C app.git remote update

Two lines in a nightly cron and every repository on the server has a current, complete copy somewhere else. On a small server, loop over the bare repos directory and mirror each one.

Bundle for portability

For a single-file, copy-anywhere backup of one repo:

git bundle create app-2026-10-21.bundle --all

A bundle is a real Git pack: git clone app-2026-10-21.bundle app reconstructs the repository on any machine with Git and nothing else. Bundles are the right shape for weekly off-site copies - one dated file per repo, uploaded to object storage or another box.

Copy what Git does not track

The repositories are the obvious half. The other half lives next to them: server hooks (your deploy and protection scripts), the Git host's own configuration, user and access data. A plain rsync -a of those directories into the same off-site destination covers it. Losing the repos is painful; losing the hooks and config is what turns a restore into a rebuild.

Rehearse the restore

A backup you have never restored is a hope, not a plan. Once a month, pick one bundle or mirror and restore it to scratch space: clone from it, run the test suite, check the latest commits are there. Ten minutes, and the night the server actually dies becomes an inconvenience instead of an incident.

The honest summary: mirror nightly, bundle weekly off-site, rsync the config, restore monthly. Four small habits, and the machine your whole team depends on stops being a single point of failure.

Branch Naming Conventions That Scale Past Three People

Wed, 21 Oct 2026 00:00:00 GMT

With two developers, branch names do not matter - you both know what everything is. Add a third, then a fifth, and suddenly fix-stuff and stefan-wip-2 are a shared inbox full of unmarked letters. A naming convention is not bureaucracy; it is how a branch list becomes readable at a glance.

The shape that works

BILL-88-retry-failed-invoices
feature/team-invitations
hotfix/checkout-double-charge

Three ingredients, in rough order of value:

A ticket reference when one exists. BILL-88-retry-failed-invoices links the branch to the tracker without opening anything. Tools pick this up automatically - GitHub and GitLab cross-reference, and the PR inherits the link. When there is no ticket, skip it; inventing ceremony for a typo fix is worse than omitting it.
Lowercase words joined by dashes. No underscores, no camelCase, no spaces escaped into %20. Branch names appear in URLs, CI logs and shell commands; the boring format survives all three.
A type prefix for the exceptions. hotfix/ and release/ prefixes earn their keep because they signal urgency and different rules - a hotfix skips the queue (see shipping a hotfix without the drama). Feature branches need no prefix; they are the default case.

The conventions that collapse

Names as ownership. stefan-billing tells you who, not what - and the moment two people touch it, the name is a lie. Ownership lives in the PR assignee, not the branch.

Version branches that never die. v2-redesign living for four months is not a branch, it is a fork with anxiety. If work takes that long, the answer is feature flags and incremental merges, not a longer-lived branch name.

Over-specified formats. type/TEAM-1234/short-description/v1 looks great in a wiki and collapses on contact with reality. Every required element is a place to be wrong.

Pair it with cleanup

Names decay faster than branches. A convention only stays legible if merged branches get deleted - most hosts offer this as a button or an automatic setting - and stale ones get pruned locally (git fetch --prune, or the config version in five git config settings worth changing). A branch list of twelve current names beats a list of two hundred historical ones, whatever convention they follow.

Pick the boring format, write it in CONTRIBUTING.md, and spend the saved energy on the work the branches exist for.

Branch Protection Rules That Stick

Wed, 21 Oct 2026 00:00:00 GMT

Branch protection fails in two ways: too little of it, and so much of it that the team routes around it. For a small team, three rules do most of the work.

1. Require a pull request and one review

Nobody pushes straight to main, including the senior who "just fixes a typo". One reviewer is enough at this size — the point is a second pair of eyes, not a committee.

2. Require checks to pass

The test suite runs on the PR and must be green before merge. This is what keeps "main always runs" true in practice rather than in principle. If the suite is slow, fix the suite — do not downgrade the rule to "tests optional".

3. No force-pushes to main

Shared history is append-only. Rewriting main breaks everyone's clones and makes the audit trail meaningless. Rebasing stays on feature branches, where it belongs.

What to leave out until it hurts

Code-owner reviews, signed-commit requirements, linear-history-only, status checks from five tools — each adds friction that makes sense at a specific size or risk level. Add them when a real incident names the need, not because the settings page offers them.

The test of a ruleset is whether the team still respects it in month six. Small and enforced beats thorough and bypassed.

Cherry-Picking: One Commit Without the Branch

Wed, 21 Oct 2026 00:00:00 GMT

A branch has ten commits and you need one of them - not the merge, not the history, just that change, on your branch. That is cherry-pick's whole job.

The basic move

Find the hash on the source branch, then apply it where you stand:

git log --oneline release/1.4
git switch main
git cherry-pick 332a818

Git replays that commit's diff on your current branch and makes a new commit with the same message. Note the new commit gets a new hash: the parent is different, so it is a copy, not a move - the original still lives on its branch.

Record where it came from

git cherry-pick -x 332a818

-x appends "(cherry picked from commit ...)" to the message. Six weeks later, when the release branch and main both contain what looks like the same fix, that line is the difference between "already backported" and an hour of comparing diffs. Use it every time the source branch will keep existing.

When it fights back

A cherry-pick can conflict exactly like a merge, usually because the surrounding code drifted between the branches. Resolve the files, then:

git cherry-pick --continue   # or: git cherry-pick --abort

--abort puts the branch back as if you never started, so a pick that is turning into a rewrite costs nothing to abandon.

The Laravel-shaped case

A hotfix lands on main during the week; the release branch for 1.4 tags on Friday and needs that fix but none of the week's other work. Cherry-pick it with -x, run the suite, tag. The release notes stay honest and the histories traceable.

Where it goes wrong

Cherry-pick is for exceptions, and it turns sour as routine:

The same fix picked onto four branches is four divergent commits to reconcile later. If every active branch needs a change, land it on the oldest branch that needs it and merge forward instead.
Picking whole features commit-by-commit rewrites review history into a queue of conflicts. That is what rebases and merges are for.
Because the copy has a new hash, tooling that matches commits by hash - and teammates comparing branches - will see two commits. -x keeps that readable.

Used sparingly and always with -x, cherry-pick is the scalpel of the toolbox: not how you move work, exactly how you move one piece of it.

Cleaning Untracked Files Without Regret

Wed, 21 Oct 2026 00:00:00 GMT

Untracked files accumulate: scratch scripts, a dump from debugging, build leftovers from a branch with different tooling, the config copy you made "just for a minute". git clean is how you clear them - and it is one of the few Git commands whose victims are genuinely unrecoverable, because untracked files exist in no commit, no stash, no reflog.

Always dry-run first

git clean -nd

-n lists what would go, without touching anything. -d includes directories, which is where most of the mess lives. Read the list; if it is all junk, run it for real:

git clean -fd

That is the whole safe workflow: -n, read, then -f.

The -x warning, especially on Laravel apps

git clean -fdx

-x also removes ignored files - everything in your .gitignore. On a Laravel project that includes .env, and git clean -fdx deletes your .env with no backup and no recovery. It also deletes vendor/ and node_modules/, which at least reinstall.

Reach for -x only when you truly mean "make this clone pristine" - and even then, copy .env aside first. The everyday clean is -fd without the x.

Pick instead of sweeping

git clean -i

Interactive mode lists candidates and lets you choose one by one, by pattern, or toggle each. Right answer when the directory mixes junk with files you are not sure about.

What not to clean

Framework caches are not git clean territory. Stale config, route and view caches on a Laravel app belong to php artisan optimize:clear - it knows what to rebuild and touches nothing else. Save git clean for what the framework does not own: experiment leftovers, wrong-branch artifacts, scratch files.

And when you are unsure whether something is junk, that is what git stash -u is for. A stash can be popped next week; a cleaned file cannot come back at all.

CODEOWNERS Files: Automatic Reviewers for the Risky Parts of Your Repo

Wed, 21 Oct 2026 00:00:00 GMT

Some pull requests are fine with any reviewer. Some are not: a migration touching a billing table, a change to the deploy script, a tweak to authentication middleware. For those, you want a specific pair of eyes - and you want that to happen by default, not because someone remembered to ask.

A CODEOWNERS file encodes that routing. When a pull request touches a path with an owner, the platform automatically requests the owner's review, and branch protection can require their approval before merge.

The syntax

The file lives at .github/CODEOWNERS (GitHub) or .gitlab/CODEOWNERS (GitLab), and each line is a pattern followed by one or more owners:

# Default owner for everything
* @stefan

# Database changes need the data team
database/migrations/ @stefan @amira

# Deploy and CI config
deploy.sh @ops-team
.github/workflows/ @ops-team

# One specific file
config/services.php @stefan

Patterns follow gitignore-style matching. Later lines override earlier ones for the paths they match, so put the general rules first and the specific ones last.

Where Laravel teams get the most value

You do not need to own every path. Two or three rules cover most of the risk:

database/migrations/ - migrations are hard to roll back and easy to get subtly wrong. Our post on reviewing migrations is the checklist your owner will run through.
Deploy and CI configuration - deploy.sh, workflow files, docker-compose.yml. A broken deploy script costs the whole team's afternoon.
Auth and payment code - the directories where a mistake is a security incident or a billing bug, not just a UI glitch.

Everything else can stay with the team-wide default: anyone reviews, someone approves.

The failure modes

Owner becomes a bottleneck. If every migration needs one person's approval and they are on holiday, work stops. Name at least two owners for critical paths, and keep the required-approvals count at one.

File goes stale. People change roles, teams change shape. A CODEOWNERS file pointing at someone who left is worse than none - it creates the illusion of review. Re-read it when the team changes, the same way you re-read branch protection rules.

Ownership as territory. The file routes review; it does not grant veto over ideas. If "owner approval required" starts meaning "nobody else may touch this," that is a team problem the file merely made visible.

Start small: one file, three rules, two owners per critical path. The first time an automatic review request catches a risky migration before it merges, the file has paid for itself.

Conventional Commits for a Small Team

Wed, 21 Oct 2026 00:00:00 GMT

Six months of commit messages that say "fix", "wip" and "changes" tell the next developer nothing - and on a small team the next developer is usually you. Conventional Commits add one prefix to every message and turn the log into something you can actually read.

The whole format

type(scope): short summary

The types that earn their keep on a Laravel app:

feat - new behaviour (feat(billing): add invoice PDF download)
fix - a bug (fix(queue): stop retrying permanently failed jobs)
refactor - same behaviour, different code
test - tests only
chore - dependencies, config, tooling
docs - the README and friends

The scope is optional but cheap: one word naming the part of the app (billing, queue, auth). The summary stays imperative and under about 70 characters.

What it buys

git log --oneline becomes a changelog draft: everything user-visible is a feat or fix, everything else filters out. That is exactly the input the tags-to-changelog habit needs, and it makes releases a paste-and-edit job instead of an archaeology dig. Review gets faster too - a refactor prefix sets expectations before the diff loads, and nobody hunts for behaviour changes in a commit that announced there are none.

Breaking changes get a ! (feat(api)!: drop v1 endpoints) or a BREAKING CHANGE: footer, so they are impossible to miss at release time.

Adopt it without a fight

The failure mode is process, not spelling: a team that gets a 12-type spec and a CI gate on day one starts writing chore: stuff to make the check pass. Start smaller:

Five or six types, written in the README or pull request template.
Scope optional, body only when the why is not obvious from the diff.
No CI enforcement at first. Squash-merge pull requests and write the conventional message on the squash commit - main stays clean even when the branch's own commits are messy.

If it still feels like overhead after a month, drop it. A convention the team half-follows is worse than none, because it teaches people the log cannot be trusted. The bar is not a perfect history; it is a git log you can skim before a release and believe.

Deploy Keys and Machine Users: Giving CI Access Without Handing Over Yours

Wed, 21 Oct 2026 00:00:00 GMT

Somewhere in the early days of many teams, someone generated a key on the CI server and added it to a developer's GitHub account "just to get the build working." That key now has that person's full access to every repo they can touch - readable by anyone who can read the CI config. This is the access equivalent of the committed-secret problem in a secret got committed, now what, and it deserves the same urgency.

Deploy keys: read-only, one repo

A deploy key is an SSH key attached to a single repository, not to a person. GitHub and GitLab both support them, and both let you make the key read-only.

Use one when CI needs to clone one repo: your app repo for the test pipeline, the deployment target pulling code on the server. Generate a dedicated keypair on the machine, add the public half as a deploy key with read-only access, and revoke it by deleting the key - no person's account involved. If you followed our SSH keys guide, this is the same mechanics, pointed at a repo instead of a user.

The limitation is real: one deploy key cannot span repos. If CI must pull private Composer or npm packages from sibling repositories, a deploy key per repo works but multiplies keys fast.

Machine users and fine-grained tokens

When CI genuinely needs several private repos - a Laravel app plus two private packages - the options widen:

A machine user: a separate GitHub account that exists only for automation, granted read access to exactly the repos CI needs. Simple to reason about, and access is visible in the repo's collaborator list. Costs a seat on some plans.
A fine-grained personal access token: scoped to specific repositories, read-only contents permission, with an expiry date. Lighter than a machine user, and the expiry forces regular rotation. Use the shortest expiry your rotation process can keep up with.

What both avoid is the original sin: a credential tied to a human's full access, valid forever, sitting in a CI variable.

The rules that matter

Whatever mechanism you pick, three rules keep it healthy:

Read-only by default. CI that only clones needs no write access. Grant push only to jobs that genuinely push (a release workflow tagging a version), and only on that job.
One credential per consumer. The staging server's key and the CI key are different keys, so revoking one never breaks the other and a leak has a smaller blast radius.
Rotation you can actually do. A credential you cannot rotate without a meeting will never be rotated. Keep a short note of where each key lives; the day one leaks, you want a five-minute fix, not archaeology.

Access for automation is a solved problem - the only wrong answer left is your personal key in a CI variable.

Deploy With Tags, Not Branches

Wed, 21 Oct 2026 00:00:00 GMT

A common small-team setup has a production branch: merge into it, push, and the server pulls it. It works until the day someone commits directly to it, force-pushes it, or merges the wrong thing and the branch history no longer matches what anyone intended. The branch stops being a record and becomes a rumor.

A tag does not have these problems.

What deploying a tag looks like

The release flow is: finish work on main, tag the commit, deploy the tag.

git tag -a v1.14.0 -m "v1.14.0"
git push origin v1.14.0

On the server, instead of git pull, the deploy script fetches and checks out the exact tag:

git fetch --tags
git checkout v1.14.0

That is a detached HEAD on purpose - the server is not a place where commits happen, so there is nothing to lose. The result is that "what is running in production" has one unambiguous answer, and it is the same answer git tag gives everyone on the team.

Why this beats an environment branch

Tags do not drift. A branch can pick up a stray commit; a tag points at one commit forever.
Rollback is a checkout. Deploy the previous tag and you are back, with no revert commit needed - When to Reset, Restore, or Revert stays a developer-machine topic, not a 2 AM production topic.
The release log writes itself. Tag messages and annotated-tag history double as the skeleton of a changelog, which is the whole trick in Keep a Changelog Straight From Git Tags.

The Tagging Releases Properly post covers annotation and naming; this one is about making the tag the unit of deployment.

Keeping staging honest

If you want a staging environment, deploy the same way: tag a release candidate (v1.14.0-rc.1), deploy that tag to staging, and promote by re-tagging or tagging the final release on the same commit. "Staging runs something production has never seen" becomes structurally impossible.

For the full pipeline around this - build steps, env handling, the push-to-server mechanics - Deploy Laravel With Git Push walks through it. The short version of both posts: branches are for work in progress, tags are for facts. Deploy facts.

Does Your Team Need a Merge Queue? Probably Not Yet

Wed, 21 Oct 2026 00:00:00 GMT

A merge queue is CI's answer to a sneaky failure: two pull requests, each green against main, that break when combined. One renames a function; the other adds a new call to the old name. Both pass, both merge, main is red. The queue fixes this by testing each PR against main plus everything already queued, so "green" means "green against what main will actually be."

GitHub, GitLab and Bors all offer one. The question is not whether they work - they do - but whether your team has the problem they solve.

The threshold

The broken-main-from-colliding-PRs problem needs two ingredients: enough parallel merges that collisions are likely, and a test suite slow enough that "just rebase and rerun CI" is painful. A team merging three pull requests a day with a five-minute suite almost never sees it. A team merging thirty a day with a forty-minute suite sees it weekly.

Some honest signals you have crossed the line:

Main breaks from semantic conflicts more than once a month, and each break costs real debugging time.
Reviewers ask authors to "rebase and make sure it is still green" so often that the rebase-rerun loop is the bottleneck.
Releases get delayed because main went red at the wrong moment.

What to do before you get there

Most small teams get the same protection cheaper:

Keep CI fast. A five-minute suite makes "rebase and rerun" a shrug, not an afternoon. This is the same investment as always - shallow clones and dependency caching - and it pays whether or not you ever need a queue.
Require branches to be up to date before merging on the riskiest repo. GitHub's branch protection has this checkbox; it forces the rebase-rerun loop explicitly, which is exactly a manual merge queue. Fine at low volume, painful at high volume - which is your signal.
Merge promptly after approval. Most collisions happen because approved PRs sit for days while main moves on. A queue will not fix a review-and-forget habit; small pull requests will.

When the manual loop becomes the thing slowing everyone down, the queue stops being infrastructure cosplay and starts paying rent. Until then, the honest answer is: not yet - and here is how you will know.

Use Draft Pull Requests to Get Feedback Early

Wed, 21 Oct 2026 00:00:00 GMT

The traditional pull request arrives finished: code done, tests written, author braced for judgment. By that point the expensive decisions are locked in, and "have you considered a different approach?" means redoing two days of work. A draft PR flips the order - feedback lands while changing course is still cheap.

What a draft is for

Open the PR as a draft the moment the shape of the change exists: the migration, a sketched controller, maybe a failing test that names the behavior. The draft status says plainly: do not review the details yet, do look at the direction.

That early look catches the reviews that matter most:

"This duplicates what the billing package already does" - before you polish your version.
"The column should live on the invoices table, not the users table" - before the migration ships.
"We tried this approach in March, here is why it hurt" - before you rediscover March.

The working agreement

Drafts only work if the team reads them in the right spirit. Two conventions keep it healthy:

The author says what they want. "Does this structure make sense?" gets a useful answer; silence about intent gets either no review or a full one you did not want yet. The PR description matters more, not less, in a draft.
Nobody treats a draft as a promise. Scope can shrink, approach can change, the branch can be rebased - drafts are force-push-with-lease territory by default.

Marking the PR ready for review is then a real signal: the direction is settled, now judge the details.

The quiet side benefit

Drafts double as a status board. A team that opens drafts early can see what is in flight without asking - which prevents the awkward moment where two people discover at merge time that they both spent the week on the same invoice controller. It also feeds the habit that keeps everything else moving: work arrives in small, reviewable pieces, because a draft that has been open for three weeks is visibly not that.

Open it early, say what you want, mark it ready when it is. The PR stops being a verdict and becomes a conversation - which was the point of having a team.

Feature Flags: How to Merge Daily Without Shipping Half-Built Work

Wed, 21 Oct 2026 00:00:00 GMT

The argument for a long-lived feature branch goes: the work takes three weeks, it cannot ship half-done, so it lives on a branch until it is ready. The cost shows up at the end - a three-week merge, conflicts with everything that moved underneath, and a review nobody can hold in their head.

Feature flags attack the premise instead of the branch. If unfinished code can sit in production safely, invisible behind a flag, there is no reason to keep it out of main.

What a feature flag is

A flag is a runtime check around new behaviour:

if (feature('new-billing-dashboard')) {
    return view('billing.dashboard-new');
}
return view('billing.dashboard');

Laravel teams have good options for the feature() part: Laravel Pennant (first-party, ships with recent Laravel versions), a config value, or an external service. The mechanism matters less than the habit: new behaviour ships dark, off by default, and turns on when it is ready - per user, per team, or for everyone.

Why it pairs with trunk-based development

Trunk-based development asks for small, frequent merges into main. The objection is always "but my feature is not done." Flags answer it: merge the first slice behind a flag on Monday, the second on Wednesday, the third next week. Each merge is small, reviewed quickly, and deployed continuously - while users see nothing until you flip the flag.

The bonus nobody expects: rolling out to 5% of users, then 50%, then everyone is free. And if something breaks, "roll back" is turning the flag off - no revert deploy, no drama, exactly the cheap-exit thinking in rollback or roll forward.

The disciplines that keep flags healthy

Name flags for the feature, not the date. new-billing-dashboard is clear in six months; experiment-2026-10 is not.

Flag the smallest unit of behaviour. One flag around one feature. A flag that controls three unrelated things cannot be turned off cleanly when one of them misbehaves.

Delete flags when the rollout finishes. A flag that stays at 100% forever is an if statement with extra steps. Make "remove the flag" the last task on the feature ticket, and grep for stale flags every quarter. This is the unglamorous part, and the part that decides whether flags stay a tool or become sediment.

Start with one flag on your next multi-day feature. The first time you merge on day one instead of week three - and turn the thing off from your phone when it misbehaves - the branch-everything habit loses its grip.

Git Fetch vs Pull: What Your Pull Actually Does

Wed, 21 Oct 2026 00:00:00 GMT

git pull is the command everyone learns first and understands last. It is not one operation - it is git fetch followed immediately by git merge (or git rebase, depending on your config). Splitting them apart is worth the ten seconds it takes, because the second half is where surprises live.

Fetch: look before you leap

git fetch origin

Fetch downloads new commits from the remote and updates your remote-tracking branches - origin/main and friends - without touching your working tree or your local branches at all. Nothing can conflict, nothing can be overwritten. It is pure information.

That makes fetch the safe first step:

git fetch origin
git log --oneline HEAD..origin/main

The log shows exactly what arrived while you were working. If the answer is three commits you already know about, merging is a formality. If it is a force-push or a rewritten history, you found out before it landed in your branch - which is also why teams that force-push feature branches should force-push with lease.

Merge or rebase: the second half

Once fetched, you choose how to combine:

git merge origin/main - creates a merge commit when both sides moved. Honest history, extra bubbles.
git rebase origin/main - replays your unpushed commits on top, keeping history linear. Cleaner, but it rewrites your local commits, so only for work nobody else has.

git pull picks one of these for you based on config (pull.rebase, or merge by default). Teams that care should pick deliberately - Merging vs Rebasing for Small Teams is the full argument, and a one-line git config pull.rebase true (or pull.ff only) makes the default explicit instead of accidental.

A small daily upgrade

Replacing the reflexive git pull with fetch, look, then merge-or-rebase costs seconds and buys two things: no surprise merge commits in the middle of your work, and no discovering a conflict after you have mentally committed to it. When conflicts do show up, Resolving Merge Conflicts Without Panic has the rest of the drill.

The one-line summary: fetch is reading, pull is reading plus writing. Read first.

Git Bisect: Find the Commit That Broke It

Wed, 21 Oct 2026 00:00:00 GMT

Something that worked last release is broken now, and forty commits sit between then and now. Reading every diff is the slow way. git bisect does a binary search over the range, so six checks find the culprit instead of forty.

Mark the ends

git bisect start
git bisect bad            # the commit you are on is broken
git bisect good v1.4.0    # the last tag you know was fine

Git checks out a commit in the middle. Run whatever reproduces the bug — the feature test, the artisan command, the page that 500s — then tell Git the answer:

git bisect good   # or: git bisect bad

Repeat. Each answer halves the range, and after a few rounds Git names the first bad commit with its full diff and message.

Let the test suite drive

If a single command answers "is this commit broken", hand the whole search to it:

git bisect run php artisan test --filter=CheckoutTest

Bisect now walks the range alone, marks each commit from the exit code, and stops on the first failure. This is the version worth using: it is fast, and it removes the temptation to eyeball a step and guess.

Two practical bumps

A commit that cannot run at all — a dependency changed and the test cannot boot — stalls the search. git bisect skip tells Git to step over it, and git bisect run can skip automatically when the command exits with 125.
Vendored directories move between commits. Between steps you may need composer install; inside bisect run, a tiny shell script that runs it before the test keeps every commit bootable.

When it names a commit

git bisect reset

That returns you to where you started. The bisect log disappears, so note the hash first. The usual next step is not the fix — it is a failing regression test on current main that proves the bug, so the fix that follows can never quietly regress.

Bisect rewards the boring habits: small commits that each boot, and tags you can trust as "known good". Those habits are cheap right up until the day they are the fastest way back to a working app.

Git LFS: When a Laravel Repo Needs It

Wed, 21 Oct 2026 00:00:00 GMT

Every clone downloads the whole history. A 50 MB design file committed once is 50 MB in every clone forever, even after you delete it. Git LFS exists for that problem: the repo keeps a pointer, the bytes live in separate storage.

The setup

git lfs install
git lfs track "*.psd" "*.zip" "*.mp4"
git add .gitattributes

From then on, matching files are stored via LFS automatically. Existing history is untouched — only new commits use the pointer.

What belongs in LFS on a Laravel project

Genuinely version-worthy binaries: design source files, brand assets, documentation PDFs, maybe small fixture videos for tests. If the file is source material the team edits and needs history for, LFS fits.

What does not

User uploads, media libraries, anything served to visitors. Those belong in object storage with a CDN in front — Laravel's filesystem disks are built for exactly that, and your repo stays lean. The test is "does the next developer need this on a fresh clone?" If not, it is not repo content.

If the repo is already heavy

Adding LFS now does not shrink old history; that takes the same history-rewriting treatment as a leaked secret, with the same team-wide re-clone cost. Worth it when clones hurt, not before.

Keeping a Changelog From Git Tags

Wed, 21 Oct 2026 00:00:00 GMT

A changelog is only painful when you write it three months late. If you tag releases, most of the work is already done.

Tag what you ship

git tag -a v1.3.0 -m "v1.3.0"
git push origin v1.3.0

Annotated tags carry a message and a date, and they give you a name for "what is in production right now".

The log between tags is your draft

git log v1.2.0..v1.3.0 --oneline --no-merges

That list, cleaned up, is the release note. Short, descriptive commit subjects pay off here — another reason the commit-msg habit matters.

Keep a CHANGELOG.md in the repo

Add a section per tag, newest at the top, dated. Users of your package or app read it before upgrading; future-you reads it when something breaks and the question is "since when". For a Laravel app, note the migrations and any .env keys a release adds, because those are the steps a deploy can trip on.

The habit that makes it work

Write the entry at tag time, while the diff is fresh. A changelog maintained per release is ten lines of work; reconstructed quarterly it is an afternoon of archaeology.

Keeping a Fork in Sync With Upstream

Wed, 21 Oct 2026 00:00:00 GMT

Fork a repository and the clock starts: the original keeps moving, and your copy quietly becomes a snapshot of the past. Whether it is a package you patched or an internal template your team forked, syncing is the same two-remote routine.

Two remotes, two jobs

git remote add upstream git@yourgit.example.com:original/project.git
git remote -v

origin points at your fork - where you push. upstream points at the source - where you only read. Naming them this way is convention, and the convention matters: when every guide and every teammate says "upstream", everyone means the same thing.

The sync routine

git fetch upstream
git switch main
git merge upstream/main
git push origin main

Fetch first, look at what arrived (git log --oneline HEAD..upstream/main), then merge and push. This is the fetch-then-decide rhythm from Fetch vs Pull - the only difference is the remote's name. If your team prefers linear history, git rebase upstream/main works too, but only on commits that exist solely in your fork.

Keep your changes out of main

The fork stays easy to sync when your own work never touches its main. Do everything on feature branches - git switch -c our-patch - and let main mirror upstream exactly. The day you commit directly to the fork's main, every future sync becomes a merge of two real histories instead of a fast-forward, and conflicts move in permanently.

If that has already happened, the repair is usually: branch your changes off (git branch our-work), reset main back to upstream (git reset --hard upstream/main after a fetch), and push. That is a force-push to your own fork, so do it with lease and warn anyone else using the fork.

How often

Often enough that each sync is boring. Weekly keeps the diff readable; monthly is survivable; yearly turns syncing into an archaeology project. Teams running a self-hosted server can nudge this with a scheduled pipeline that fetches upstream and opens a pull request when main falls behind - boring automation for a task that should never be exciting.

Keeping Diffs Clean With .gitattributes

Wed, 21 Oct 2026 00:00:00 GMT

.gitignore decides what enters the repo; .gitattributes decides how Git treats what is in it. One small file at the root, and four annoyances quietly disappear.

Line endings that stop moving

* text=auto eol=lf

Every text file normalizes to LF in the repo, whatever editor or OS committed it. The "whole file changed" diffs that come from a Windows checkout meeting an LF repo stop happening, and this line costs you nothing on day one of a repo.

Diffs that show what matters

Lock files are for machines. Hiding their diffs keeps reviews on your code:

composer.lock -diff
package-lock.json -diff

The files still commit, still version, still deploy - they just stop producing thousand-line review noise. On GitHub, mark generated directories so they collapse by default and stay out of the language stats:

public/build/** linguist-generated=true

Hunk headers that name the function

*.php diff=php

With the PHP diff driver, every hunk header in a diff names the method or function it sits in, not whatever line happened to be nearby. Reviewing git log -p on a large model gets noticeably easier.

Cleaner package downloads

If any repo is ever installed as a Composer package, export-ignore keeps its development baggage out of other people's vendor/:

/tests export-ignore
/.github export-ignore
/phpunit.xml export-ignore

End users download the code, not your CI.

None of this is mandatory and none of it changes what runs. It is housekeeping: the diffs get shorter, the reviews get faster, and the repo stops leaking its working files into places they never belonged.

Keeping Files Out of Git: ignore, exclude, and the Global File

Wed, 21 Oct 2026 00:00:00 GMT

What Not to Commit in a Laravel Project covers which files stay out of the repo. This is the mechanics post: Git gives you three different places to say "ignore this", and they are not interchangeable.

.gitignore: the shared, committed one

The .gitignore at the root of the repo is committed, so every clone gets it. This is where project-level rules live - Laravel's default file already covers the essentials:

/vendor
/node_modules
.env
/storage/logs

If a file would be junk for anyone who clones the project, its rule belongs here.

.git/info/exclude: private to your clone

This file works exactly like .gitignore but is not committed or pushed. Use it for things only your checkout produces - a scratch script you keep in the project root, a local docker-compose.override.yml nobody else has. Nobody else's repo should carry rules for your personal files.

The global file: private to your machine

Editor and OS noise follows you across every project, so Git lets you ignore it once, everywhere:

git config --global core.excludesFile ~/.gitignore_global

Put .idea/, .vscode/, .DS_Store and friends in there. If every project's committed .gitignore carries editor rules, that is a sign this file is missing on someone's machine.

When the file is already tracked

An ignore rule does nothing for a file Git is already tracking - the classic case is a .env committed before the rule existed. Untrack it without deleting your local copy:

git rm --cached .env

Commit that removal and the ignore rule takes over from there. Note the file still exists in history; if what slipped in was a secret, untracking is not enough - see A Secret Got Committed. Now What?.

One last habit: run git status before committing and actually read the list. Ignoring rules prevent accidents, but the status list is where you catch the ones that got through.

Commit Your Lockfiles (and How to Survive Their Conflicts)

Wed, 21 Oct 2026 00:00:00 GMT

Every so often someone proposes gitignoring composer.lock or package-lock.json "because they cause conflicts." That trades a small recurring cost for a large hidden one: without the lockfile, every machine resolves dependencies independently, and "works on my machine" becomes structural.

Why the lockfile is committed

composer.json says what you allow; composer.lock says what you got - exact versions, exact hashes. Committing it means CI, staging, production, and every laptop install the same dependency set. Your CI pipeline relies on this: composer install and npm ci read the lockfiles, which is why a green PR means something.

Without them, a package author publishing a patch release between your test and your deploy is an unreviewed code change in production.

When they conflict

Two branches both ran composer update or npm install, and now the lockfiles conflict on merge. The rule is: never resolve a lockfile conflict by hand-editing. Regenerate instead:

git merge main
# conflicts in composer.lock
git checkout --theirs composer.lock   # or ours; the content hardly matters
composer update --lock                 # regenerate a valid lockfile
git add composer.lock

The regenerated file is consistent by construction; a hand-merged one is two inconsistent halves glued together. Then run the test suite, because the merge may have combined two dependency sets that each passed alone.

For package-lock.json the same shape: take one side, npm install, commit the result.

The habits that keep it rare

One person upgrades dependencies per branch; upgrades go in their own PR, never smuggled inside a feature.
Merge or rebase frequently - short-lived branches shrink the window where two lockfiles diverge.
When you do upgrade, read the lockfile diff in the PR. It is the one diff that lists exactly what new code will run on your server.

The lockfile is the receipt for your dependencies. Keep it in Git, regenerate it instead of hand-merging, and dependency conflicts drop to a minor chore.

Managing .env Files Across Environments

Wed, 21 Oct 2026 00:00:00 GMT

Every Laravel app has the same three-way split: your laptop, a staging server, production. Each needs its own .env, and the .env itself must never be committed - What Not to Commit covers why. What is worth deciding deliberately is how the values get to each environment and how the team learns about new keys.

.env.example is the contract

Commit .env.example with every key and a safe placeholder value, and treat it as part of every pull request that adds configuration:

MAIL_MAILER=
QUEUE_CONNECTION=
INVOICE_SIGNING_KEY=

A new hire runs cp .env.example .env, fills in the blanks, and the app boots. A reviewer sees the new key in the PR diff without seeing its value. When someone adds a key to their local .env without updating the example, the next person's setup breaks quietly - so make "PR adds a key to .env.example" as automatic as "PR includes a migration".

Getting values to servers

Servers have no checkout step where you can edit a file by hand, so pick a delivery mechanism:

The deploy tool's secrets store (most managed deploy platforms have one).
A file written by your deploy script from your password manager or vault - never from the repo.
On a self-hosted box you administer: a plain .env in the shared directory of your releases structure, permissions 600, owned by the deploy user.

All three share one property: the value's home is outside Git, and changing it does not require a commit.

After changing values

Laravel caches config aggressively in production, so a changed .env does nothing until you rebuild the cache:

php artisan config:cache

Fold that into the deploy script and "I changed it but nothing happened" stops being a genre of bug report. Also restart the queue workers - they hold the old config in memory, same lesson as the deploy post's queue:restart.

The audit habit

Once a quarter, diff each environment's keys against .env.example: keys present on servers but missing from the example are undocumented config, and keys in the example that no environment sets are dead weight. Two minutes with comm on sorted key lists keeps the contract honest.

Secrets stay out of history - and if one ever lands there, A Secret Got Committed. Now What? is the cleanup drill.

Merging vs Rebasing on a Small Team

Wed, 21 Oct 2026 00:00:00 GMT

Few git arguments cost more than they settle. The working rule for a small team fits in one sentence: rebase your own branch, merge into main.

Rebase is for your branch

While your branch is still yours, keep it current and readable:

git fetch origin
git rebase origin/main

Your commits replay on top of main, conflicts show up in small pieces while you still remember the change, and the branch reads like a story a reviewer can follow.

Merge is for main

When the branch is done, merge it. The merge commit marks where the work landed and keeps the group's shared history untouched:

git checkout main
git merge --no-ff pr-42-branch

--no-ff keeps the feature visible as one unit, which makes the changelog draft and any later revert much easier.

What not to do

Never rebase a branch someone else has pulled. Rewriting shared history is how teammates lose work and trust the repo a little less. If it is pushed and shared, it merges.

That is the whole policy. Write it in the README and spend the argument on the code instead.

Migrations in Code Review: What to Look For

Wed, 21 Oct 2026 00:00:00 GMT

Most code review feedback is a request for changes, and the author edits the same file. Migrations break that rule: once a migration is merged and run anywhere - staging, a teammate's machine, production - the file is a fact. Editing it changes nothing that already ran and silently forks the databases that have not. Reviewing migrations well matters more than reviewing almost any other diff, because it is the last time the change is cheap.

The review checklist

Does down() actually reverse the up()? A down() that drops the table when up() added a column is a trap for the next rollback. If the change is genuinely irreversible - a dropped column - that should be a shouted comment, not a silent absence.

Are defaults and nullability safe for existing rows? Adding a NOT NULL column without a default to a table with a million rows either fails or rewrites the table while holding a lock. The safe shape is nullable first, backfill, constrain later - the same three-step dance as zero-downtime deploys require.

Did new query paths get indexes? A column added for a lookup (WHERE stripe_customer_id = ...) without an index is a slow query waiting for traffic. The migration is the cheapest place the index will ever be added.

Is data surgery mixed into schema changes? A migration that both alters a table and rewrites its rows couples "change the shape" with "change the content" in one irreversible step. Schema in migrations, data in a one-off artisan command you can rerun and monitor.

After merge: hands off

The corollary rule, worth stating in the team's written workflow: a merged migration is never edited. Found a typo in a column name after merge? A new migration renames it. This feels heavy the first time and is obviously correct the first time someone hits a database that ran the original.

Review migrations slowly, then let them harden into facts. That asymmetry - expensive to change, cheap to get right beforehand - is exactly what the habits in Code Review Habits That Actually Catch Bugs are for.

Monitoring Your Self-Hosted Git Server: The Four Things That Matter

Wed, 21 Oct 2026 00:00:00 GMT

Hosted Git comes with someone else's pager. Self-hosted means the pager is yours - which is fine, as long as it only rings for real problems. Four checks cover every failure mode a small team's Git server actually has, and none of them requires a monitoring platform you will spend a weekend configuring.

1. Is it answering?

An external uptime check hitting the web interface every minute, from outside your network. This catches the server being down, the reverse proxy dying, and the certificate expiring. Any ping service does this for free or close to it. Alert on two consecutive failures, not one - single blips are network weather.

2. Can someone actually clone?

The web UI can be green while SSH is dead, and your team notices at 9am Monday. A synthetic check that runs git ls-remote against a small repo every few minutes exercises the path that matters - SSH auth, Git daemon, disk read. A cron job on another machine with a dedicated read-only key (the deploy keys guide covers scoping it) is thirty lines of setup.

3. Is the disk filling up?

Repos only grow, and a full disk corrupts things in the order you least want. Alert at 80%, not 95% - the gap between "we should prune something this week" and "pushing is failing right now." Watch the backup destination too; it fills up quieter.

4. Did the backup actually run - and restore?

The backup cron succeeding means a file was written, not that it restores. Backing up your Git server covers the backup half; the monitoring half is two alerts: one when the backup job misses its window, and a monthly drill where you restore to a scratch machine and clone from it. The drill is the only check on this list that cannot be automated away, and the only one that proves the rest mean anything.

Four checks, one drill, and the pager stays silent for months at a time - which is exactly what "the server is fine" should feel like.

Monorepo or Many Repos for a Small Laravel Team

Wed, 21 Oct 2026 00:00:00 GMT

Laravel projects grow extra code over time: a shared package, an internal admin tool, maybe a second app that reuses the first one's domain logic. At some point you have to decide whether everything lives in one repository or gets split into several.

Start with one repo

For a small team, one repository is the right default for a simple reason: every change is atomic. When the app and its shared package live together, a rename lands in a single commit, CI runs once, and there is no version matrix to keep in your head. Composer makes this comfortable with path repositories:

"repositories": [
  { "type": "path", "url": "packages/billing" }
],
"require": {
  "acme/billing": "*"
}

The package sits in packages/billing inside the same repo, and Composer symlinks it in. You get the directory structure of a split without any of the coordination cost.

When splitting starts to make sense

Split a repo only when one of these becomes true:

A package is genuinely reused across projects with different release cadences, and tagging it independently matters.
Different people should have different access rights - a contractor on the marketing site should not see billing code.
CI time is dominated by unrelated code, and path-scoped pipelines cannot fix it.

"One day this might be an open-source package" is not on the list. That day can be handled when it arrives.

Splitting later, keeping history

When the day comes, you do not have to lose history. git subtree split extracts a directory into its own branch with every commit that touched it, ready to push into a fresh repository:

git subtree split --prefix=packages/billing -b billing-history

That is a much better story than the usual alternative of planning repository topology up front for a future that may never happen. It is also worth contrasting with submodules, which solve a different problem - vendoring an outside dependency with its own history - and bring real day-to-day friction.

The short version: one repo until something concrete hurts, path repositories for internal packages, subtree split when a package earns its independence. Repository topology is a scaling decision, and small teams scale by not making it early.

Branched Off the Wrong Branch? rebase --onto Moves It Cleanly

Wed, 21 Oct 2026 00:00:00 GMT

It happens to everyone: you start feature-b from feature-a because you needed its changes, and then feature-a merges - squash-merged, naturally, so its commits on main have different hashes. Now your pull request for feature-b shows ten commits instead of three, half of them already on main. Or worse, feature-a gets abandoned, and your work is sitting on a branch going nowhere.

git rebase --onto is the precise tool for both. It says: take my commits from here to here, and replay them over there.

The recipe

git rebase --onto main feature-a feature-b

Read it as: take everything on feature-b that is not on feature-a, and replay it onto main. Your three commits land on top of main, the squash-merged duplicates vanish from your branch, and the pull request shrinks to what you actually wrote.

The abandoned-branch case is identical: if feature-a is dead, the same command moves feature-b onto main without dragging the dead work along.

After the move

Your branch was rewritten, so the push needs the safe force:

git push --force-with-lease

That is the whole workflow - the force-with-lease guide covers why the flag matters. If the rebase hits conflicts, resolve them the same way as any merge conflict; Git stops at each conflicting commit and lets you continue with git rebase --continue.

Preventing the tangle

Stacking branches is sometimes unavoidable, but two habits make it rare:

Branch from main by default. Before git switch -c, glance at where you are. Half of all wrong-base branches are born in a hurry.
Prefer small pull requests. A PR that merges in a day is rarely something you need to build on top of; a PR that sits for two weeks practically forces stacking.

And when stacking is genuinely needed - a big feature split into dependent slices - note the dependency in the pull request description, so nobody merges the second slice first.

rebase --onto looks intimidating in the manual and is three words in practice. Learn it once and the wrong-branch mistake stops costing an afternoon.

Moving Your Repositories to a New Git Server Without Losing Anything

Wed, 21 Oct 2026 00:00:00 GMT

Moving hosts feels risky because the repo is the crown jewels. The good news: Git is a distributed system, and every clone already contains the complete history. Migrating is mostly a matter of pushing that history somewhere new - plus remembering the things that are not in the repo.

The mirror push

The recipe for a lossless move is three commands:

git clone --mirror git@old-host:your-org/your-app.git
cd your-app.git
git push --mirror git@new-host:your-org/your-app.git

--mirror on the clone fetches every branch, every tag, every note - not just the default branch checkout. --mirror on the push replicates all of it, exactly, onto the new server. When the push finishes, the new repo is a bit-for-bit copy of the old one's refs. History, tags, branches: done.

What does not travel

The repository is only part of what makes a project work. Plan separately for:

Pull requests and issues. These live in the host's database, not in Git. GitHub's API can export them; some teams archive them to a document and start fresh, some use migration tooling. Decide consciously - do not discover the gap after the cutover.
CI secrets and variables. Re-enter them on the new side. This is also a natural moment to apply the scoping rules from deploy keys and machine users instead of copying an old personal key.
Webhooks and integrations. Deploy hooks, Slack notifications, status checks - make a list before you start, and tick each one off on the new server.
Branch protection rules. Recreate them; branch protection rules that stick is the checklist.

The order that avoids pain

Set up the new server and recreate protections while the old one still serves everyone.
Mirror-push every repo, and spot-check: clone from the new host, run the test suite, compare git log on a few branches.
Move one non-critical repo first as a dress rehearsal for the team's workflow changes.
Announce a short freeze on the old host, do a final mirror push to catch the last commits, then update everyone's remotes: git remote set-url origin git@new-host:your-org/your-app.git.
Keep the old host read-only for a month. Deleting it on day one is how you find out what you forgot.

If you are moving to self-hosted, the prep work is the same - plus the operational habits in backing up your Git server from day one, because the safety net is now yours to run.

The history is the easy part; Git was built for this. The checklist above is the difference between a quiet migration and a week of "did anyone move the webhook?"

Onboarding a New Developer to Your Git Workflow

Wed, 21 Oct 2026 00:00:00 GMT

Every team has a Git workflow, but most teams keep it in their heads. A new developer then learns it by breaking it: committing to the wrong branch, force-pushing the wrong thing, opening a 2,000-line PR on day three. A one-page written workflow and a little automation fix most of this before it happens.

Write down the five decisions

However your team works, these five choices define it. Put them in the README or CONTRIBUTING.md:

Where work happens: feature branches off main, or straight to main for tiny teams.
How branches are named: feature/short-name, fix/thing, whatever - consistency matters more than the scheme.
What a pull request needs: description, linked ticket, one approval, green CI.
How merges land: merge commit, squash, or rebase - Merging vs Rebasing for Small Teams if this is still unsettled.
How releases happen: tags, changelogs, deploy steps. Tagging Releases Properly covers the shape.

A new hire who can read those five lines commits correctly on day one.

Automate what is enforceable

Rules that live only in the document decay. The ones that survive are enforced by the repo itself:

Branch protection on main, so "don't push to main" is a fact, not a preference.
Git hooks for the local checks - Pint, tests, no debugging leftovers.
Conventional commits if the team wants parseable history, with a commit-msg hook to back it.

Automation also shortens the document: you stop writing rules down once the tooling states them for you.

Pair on the first pull request

The highest-leverage onboarding hour is walking a new developer through their first PR the team's way: small branch, tidy commits, a description a stranger could review from, responding to comments without defensiveness. Point them at the team's own posts on small pull requests and PR descriptions if you have them - or write yours down once and link it forever.

The measure of a good onboarding is how boring the second week is: the new hire ships a small PR, gets one round of comments, merges, and nobody had to correct a Git habit. That outcome is designed, not lucky.

Private Composer Packages Straight From Your Own Git Server

Wed, 21 Oct 2026 00:00:00 GMT

Every growing Laravel team eventually extracts a package: the shared billing client, the internal logging helper, the theme. Then comes the assumption that serving it needs infrastructure - Satis, Private Packagist, a registry. For most teams it does not: Composer reads plain Git repositories directly, and if you already self-host your Git, the registry is running.

The VCS repository

In the consuming app, tell Composer where the package lives:

"repositories": [
    { "type": "vcs", "url": "git@git.yourcompany.com:shared/billing-client.git" }
],
"require": {
    "yourcompany/billing-client": "^1.2"
}

The package repo itself just needs a composer.json with its name and autoload config - no extra hosting. On install, Composer clones the repo over SSH and checks out the requested version. That is the whole registry.

Versions come from tags

Composer reads versions from Git tags, which makes disciplined tagging the whole game: tagging releases properly covers annotated semver tags, and the contract here is simple - tag 1.2.0 in the package repo and ^1.2 resolves to it. No tag, no release; a branch name works for dev versions (dev-main) but treat that as a development convenience, never a production dependency.

Access is the only real setup

CI and every developer need read access to the package repo. This is where teams reach for a shared key in a wiki - do not. The patterns in deploy keys and machine users apply exactly: a read-only deploy key per consumer, or a machine user with access to the package repos. Developers authenticate with their own SSH keys, which they already have.

When you outgrow it

The direct-VCS approach slows down at scale: Composer clones every package repo on every install, and metadata lookups multiply. The honest thresholds are dozens of packages or very slow CI installs, and the upgrade path is Satis (static, self-hosted, stays on-brand) generating metadata over the same repos. Until then, VCS entries plus tags cover the need with zero new infrastructure.

Your Git server already hosts the code. Let it host the packages too.

Pull Request Templates That People Actually Fill In

Wed, 21 Oct 2026 00:00:00 GMT

A pull request with an empty description is a small act of unkindness to its reviewer. They have to reconstruct the intent from the diff, guess at the testing, and ask questions the author could have answered in thirty seconds. Teams fix this with a template - then often ruin it by making the template a questionnaire nobody reads.

What a template is for

Drop a file at .github/pull_request_template.md (or .gitlab/merge_request_templates/Default.md) and every new pull request starts with its contents pre-filled. The author's job shifts from "write something from nothing" to "fill in the blanks" - which is a much lower bar, and that is the whole point.

The sections that earn their place

Three prompts cover almost everything a reviewer needs:

## What
One or two sentences: what does this change do?

## Why
What problem does it solve? Link the ticket if there is one.

## How tested
What did you run, click, or deploy to staging to convince yourself?

"What" and "why" are the difference between a review and an interrogation. "How tested" is the one authors skip when there is no prompt, and the one that catches "I did not actually run it" before the reviewer does.

For risky changes, one optional line helps: **Risk:** what breaks if this is wrong? Leave it in the template as a comment or optional heading, and the answer doubles as your rollback plan - which pairs well with the habits in rollback or roll forward.

What to leave out

Every field you add is a tax on every pull request. Skip:

Long checklists of things CI already checks. "Tests pass" is a status badge, not a checkbox.
Legalistic boilerplate. Nobody has ever been protected by "I confirm I have read the contributing guide."
Sections that only apply to one pull request in fifty. Database migration notes, screenshots, API changes - authors will add these when relevant. A heading they must delete is friction, not help.

If a section is empty on most merged pull requests, cut it.

Keep it alive

A template is a living document with exactly one success metric: do merged pull requests have useful descriptions? Skim the last ten. If "How tested" is always "yes", sharpen the prompt ("what command did you run?"). If a section is always deleted, remove it.

The template is also a forcing function for smaller work: a pull request too big to describe in two sentences is a pull request that should be split, which is exactly the argument in small pull requests get reviewed faster. And when the description is written, the advice in writing a good pull request description makes it land.

Start with three headings and resist every addition. The best template is the one nobody notices.

Reading Git History: The log Flags Worth Knowing

Wed, 21 Oct 2026 00:00:00 GMT

Plain git log prints every commit at full width, oldest context buried pages deep. Nobody reads it. The flags below are the difference between archaeology and a quick look at the map.

The map

git log --oneline --graph --decorate

One line per commit, branch structure drawn, branches and tags labelled. Add --all to see every branch at once instead of just the one you are on. This combination answers "where is everything right now" faster than any GUI, and it is the natural first step before a rebase or a release.

The filter

git log --oneline --since="2 weeks ago" --author=sara

Time and author filters narrow the noise. The one that earns its keep before a release:

git log --oneline v1.4.0..main

Everything on main since the tag - exactly the input a changelog needs.

The detail

When a commit list shows something interesting, two flags show what it did without leaving the log:

git log --stat     # files changed and how much
git log -p         # the full diff per commit

The tracers

Two more for tracking specific things through time:

git log --follow -p -- app/Models/Invoice.php   # history across renames
git log -S 'QUEUE_CONNECTION' --oneline          # when did this string appear or vanish

--follow matters on Laravel apps, where files move as the structure settles; the pickaxe (-S) finds the commit that introduced or removed a setting, a call, or a constant.

What a branch actually adds

Before reviewing or merging:

git log --oneline main..feature/invoice-pdf

Just the commits the branch contributes, nothing main already has. Pair with git diff main...feature/invoice-pdf --stat and you know the shape of a PR before opening it.

None of this needs memorising as a wall of flags. Keep the map (--oneline --graph --decorate) as a shell alias, learn the range form (a..b), and look the rest up when you need it - the habit that matters is reading history before you change it.

Release Notes People Actually Read

Wed, 21 Oct 2026 00:00:00 GMT

Two artifacts get confused constantly. The changelog answers "what changed, exactly" for developers - keep a changelog from git tags covers generating one honestly. Release notes answer a different question for a different reader: "what can I do now that I could not before, and did anything I rely on change?" Users, not maintainers. The mistake is shipping the ledger to the letter's audience.

Lead with what the reader gets

Not "Fixed bug in invoice retry logic" but "Failed invoice payments now retry automatically - no more manual re-runs." Same change, different subject. The test for each line: can a user tell whether to care in five seconds? If the change is invisible to them - refactors, dependency bumps, internal cleanup - it does not belong in release notes at all. It belongs in the changelog, which is exactly why having both frees you.

The shape that works

Three groups, in this order, skipping any that are empty:

New - capabilities, with a sentence on when you would reach for each.
Improved and fixed - changes to things people already use, phrased from their side ("exports are faster", not "optimized query").
Breaking and action needed - the section everyone reads first even though it is last. Anything requiring a config change, a migration, or a new minimum version goes here, with the exact step to take. Hiding a breaking change in the fixed list is how release notes lose trust permanently.

The habits behind good notes

Write the note with the PR, not at release time. One line in the pull request description - "release note: ..." - while the context is fresh beats reconstructing twenty changes from commit messages on release day. Your PR template can carry the prompt.

Tie notes to the tag. Notes ship when the version ships - see deploy with tags, not branches - so "what is in production" and "what do the notes say" can never drift.

Keep a human pass. Generated drafts are a fine start; a generated final is a ledger wearing the letter's clothes. Ten minutes of editing per release is the whole cost.

Users who trust your release notes read them. That trust is built line by line, and spent in one "everything changed, nothing says why."

Rerere: Stop Solving the Same Merge Conflict Twice

Wed, 21 Oct 2026 00:00:00 GMT

If you keep a long-lived branch - a big feature, a fork of a config file, a redesign - you know the ritual: merge main in, resolve the same conflict in the same file, again, every week. Git has a built-in answer almost nobody turns on: rerere, short for "reuse recorded resolution".

One flag

git config --global rerere.enabled true

From then on, whenever you resolve a conflict, Git quietly records what the conflict looked like and what you turned it into. The next time the same conflict appears - same file, same conflicting hunks - Git applies your recorded resolution automatically and tells you it did:

Resolved 'routes/web.php' using previous resolution.

You still review the result and commit it yourself; rerere never commits for you. It just skips the part where you re-derive a decision you already made.

Where it earns its keep

Long-lived feature branches that merge main regularly: the recurring conflicts stop recurring.
Rebase-heavy workflows: a rebase replays commits one by one, so the same conflict can surface at several steps. With rerere, you solve it at the first step and the rest resolve themselves. This pairs well with the linear-history style from Merging vs Rebasing for Small Teams.
Release branches that cherry-pick: cherry-picking a set of commits onto an older branch often hits conflicts similar to ones you resolved on main.

Trust, but verify

Rerere matches conflicts by content, so it only replays when the conflict is genuinely the same - a different hunk still stops for you. Two commands keep it honest:

git rerere status    # files with recorded resolutions in play
git rerere forget    # drop a recorded resolution you no longer trust

And the normal safety nets still apply: run the tests after any auto-resolved merge, exactly as in Resolving Merge Conflicts Without Panic.

It is a one-line config change with no downside for solo or team use - each clone keeps its own recordings, and nothing is shared or pushed. Turn it on, and the second time a conflict shows up is the last time you solve it.

Resolving Merge Conflicts Without Panic

Wed, 21 Oct 2026 00:00:00 GMT

The first time Git says CONFLICT, it feels like something broke. Nothing broke. A conflict just means two branches changed the same lines and Git refuses to guess which change you want. You are the missing piece of the algorithm.

Slow down and look at the state

git status

This lists the conflicted files under "Unmerged paths". Everything else already merged cleanly - the conflict is usually much smaller than the panic suggests.

Read both sides

Open a conflicted file and you find the markers:

<<<<<<< HEAD
Route::get('/invoices', [InvoiceController::class, 'index']);
=======
Route::resource('invoices', InvoiceController::class);
>>>>>>> feature/invoice-crud

HEAD is your side - the branch you are merging into. The other side is the incoming branch. The decision is rarely "pick one": most of the time the right answer is a combination, and in this example it is deleting both lines and writing the single route the app actually needs. Edit the file until it reads correctly and every marker is gone.

Then finish properly

git add routes/web.php
git merge --continue

Two habits make this safe:

Search for leftover markers before committing: git diff --check flags them, and a quick grep -r '<<<<<<<' app routes confirms none survived.
Run the test suite after resolving, not before. The resolved state is the code that has to pass.

If it goes wrong

git merge --abort puts everything back to before the merge, any time before you commit the result. Knowing the exit exists makes the whole thing less tense. And if a conflict was resolved badly and committed, the tools from When to Reset, Restore, or Revert and the reflog get you out.

Fewer conflicts, not zero

Conflicts scale with how long branches live and how much they overlap. Small, short-lived branches - the same habit that keeps pull requests reviewable - turn most conflicts into thirty-second events. The ones that remain are usually telling you something useful: two people edited the same code because the code needed one decision, not two.

Restoring a Deleted File From Git History

Wed, 21 Oct 2026 00:00:00 GMT

Someone deleted a file three commits ago - or three months ago - and now it turns out it was load-bearing. If the file was ever committed, getting it back is a two-command job.

Find where it disappeared

git log --oneline --follow -- database/migrations/2026_09_14_100000_add_invoice_notes.php

This lists every commit that touched the file, ending with the one that deleted it. When you are not sure of the exact path, widen the search:

git log --all --oneline --diff-filter=D -- '*invoice*'

--diff-filter=D shows only commits where matching files were deleted.

Restore from before the deletion

Bring the file back from the commit just before the one that removed it:

git restore --source=HEAD~3 -- database/migrations/2026_09_14_100000_add_invoice_notes.php

The file lands in your working tree as an untracked-by-that-name restoration - review it, then commit it like any new change. Restoring a deleted migration this way, before anyone runs it in production, is exactly the Laravel-shaped case: the file matters, the history of how it vanished does not.

For a file deleted long ago, grab the hash of the last commit that had it and use that as the source instead of counting back from HEAD.

The honest limits

The file must have been committed at least once. Git only versions what it was told about.
Staged-but-never-committed work sometimes survives as a dangling blob: git fsck --lost-found can surface it. It is a long shot, but a real one.
Unstaged, uncommitted work is gone for good - the same rule as git clean and git restore.

The pattern worth keeping: deletions in Git are just commits too, and everything committed is recoverable until the day it is not - which is the same reason the server itself still needs real backups, not just a long history.

Reverting a Merge Commit (and Getting the Feature Back)

Wed, 21 Oct 2026 00:00:00 GMT

Reverting a normal commit is a one-liner. Reverting a merge commit - the one that brought a whole feature branch into main - needs an extra decision, and it plants a trap for later. Both are manageable once you know they exist.

The -m flag

A merge commit has two parents, so Git cannot know which side's changes to undo:

git revert -m 1 6d12f5a

-m 1 says "treat parent 1 as the main line" - the branch you merged into, which is main for an ordinary PR merge. The revert undoes everything the feature branch added, in a single new commit. The whole feature is out of main, history untouched, nobody re-pulls a rewritten branch.

The trap: the feature will not come back on its own

Weeks later the feature is fixed and you merge the branch again - and the merge brings almost nothing. From Git's point of view those commits are already merged: their ancestry is in main, so a new merge sees no new commits. The fact that a later revert undid their changes is content, not ancestry, and merges do not look at content.

This is the confusing part: the branch is "merged", main lacks the code, and nothing looks wrong until the deploy.

The two ways back

Revert the revert. The clean route:

git revert 52ed808   # the commit that reverted the merge

Now main has the feature's changes again, and merging the branch brings only what is genuinely new. The history reads oddly - merge, revert, revert-of-revert - but it is accurate, and accuracy beats tidy here.

Rebase the branch. If the branch is still yours and unpushed elsewhere, rebase it onto current main. The rebased commits get new hashes, so the next merge sees them as new work. This hides the oddity but rewrites the branch, with the usual force-push-with-lease implications if it was shared.

For a small team, revert-the-revert is usually right: no rewriting, and the paper trail explains the whole episode to the next person who reads git log.

When to reach for it

Reverting the merge is the right move when the whole feature has to leave main quickly - a bad release, a pulled launch - and you want it out in one reviewable commit. If only one change inside the feature is bad, revert that specific commit instead and leave the merge alone: surgical beats sweeping whenever it is an option.

How to Review a Large Pull Request Without Losing a Day

Wed, 21 Oct 2026 00:00:00 GMT

The right answer to "how do I review a 2,000-line pull request" is usually "ask for three smaller ones" - and small pull requests get reviewed faster makes that case. But sometimes the split is not happening: it is a generated migration plus its fallout, a vendored update, a refactor that only makes sense whole. Here is how to review it honestly anyway.

Read in this order

1. The description and the tests, before any source. The description tells you what the author thinks they did; the tests tell you what the code claims to guarantee. If either is missing, that is your first comment - reviewing code whose intent you are guessing is how subtle bugs get waved through.

2. The risky files, not the first files. Sort mentally by blast radius: migrations (see reviewing migrations), anything touching auth, money or deletion, config and deploy changes. These get your freshest attention and line-by-line reading. Controllers and views get pattern-level reading. Generated files, snapshots and lockfiles get a skim - nobody reviews composer.lock line by line, they verify it was regenerated (the lockfiles guide has the drill).

3. Commit by commit, if the commits are clean. A well-sequenced history is the author's own explanation of the change - this is what tidying commits before review is for. If the commits are "wip", "fix", "fix fix", abandon this step and read the full diff.

Give feedback that fits the size

The failure mode of big reviews is binary: a defeated "LGTM" or a comment list so long it reads as hostility. The useful middle is sorting your comments:

Blocking: correctness, security, data loss. Few of these, clearly marked.
Worth discussing: design questions where you could be wrong.
Not blocking: style and preference - say once, in one comment, not forty.

And say what you did: "read migrations and billing code line by line, skimmed the rest" is honest and lets the author ask a second reviewer for the parts you skimmed. Two honest partial reviews beat one pretend complete one.

The last word stays with prevention: the best large-PR review is the one that never has to happen because the next one got split.

Review Your Own Pull Request Before Anyone Else Does

Wed, 21 Oct 2026 00:00:00 GMT

By the time you open a pull request, you have read your own code a dozen times - as its author. That is exactly the problem. You see what you meant, not what you wrote. A self-review pass, done in the diff view rather than your editor, catches the gap between the two while it is still free to fix.

Read the diff, not the code

Your editor shows the final state with all the context in your head. The diff shows only what changed, which is what your reviewer gets. Open the "files changed" view - or run it locally:

git diff main...HEAD

Read it top to bottom as if a colleague sent it. The first things that jump out are usually embarrassing in a useful way: a leftover dump() in a Laravel controller, a commented-out block, a migration that adds a column the model no longer uses.

The usual suspects

A short checklist beats good intentions:

Debug leftovers: dump(), dd(), console.log, stray log channels.
Dead code: commented blocks, unused imports, variables set and never read.
Names that made sense mid-thought: $data2, $temp, $result where the domain has a real word.
Tests that prove the happy path only - the code review habits post has the reviewer-side version of this list.
Anything you cannot explain in one sentence. If you struggle, the reviewer will too.

Annotate the non-obvious parts

Some lines are strange on purpose: a workaround for a queue driver quirk, an index added for one specific report. Leave a comment on your own PR explaining them before anyone asks. It saves a review round, and it pairs naturally with a good pull request description - the description says what and why, the inline comments say "yes, this odd line is deliberate."

Self-review also keeps the whole pipeline honest: PRs stay small and reviewable, commits stay tidy, and your reviewer's attention goes to the decisions that actually need a second brain instead of the typos that needed a second pair of eyes - yours, an hour later.

Rollback or Roll Forward? Decide Before You Need To

Wed, 21 Oct 2026 00:00:00 GMT

Something is wrong in production. The temptation is to start fixing immediately - but the first decision is which direction to move: back to the last good release, or forward to a fix. Teams that decide the criteria in advance make this call in seconds; teams that improvise it make it under pressure, badly.

Roll back when you can

Going back is the better default whenever it is actually available:

The bug is in the new code, not in data the new code wrote.
No migration in this release changed the schema in a way old code cannot live with.
Your deploys are structured for it - a symlink swap back, or deploying the previous tag.

A rollback is one known-good state replacing one known-bad state. There is nothing to debug; you are simply not on fire anymore.

Roll forward when you must

Sometimes back is closed:

A destructive migration already ran - dropped or renamed columns the old code expects.
Users have created data under the new behavior, and reverting would strand or corrupt it.
The "old" state has its own known bug that this release was fixing.

Then the fix is a new commit on main, reviewed as fast as a review can responsibly go, deployed as a new release. Note what rolling forward is not: committing directly to the server's working tree. Even mid-incident, the fix goes through Git - a branch, a very short PR, a deploy - because the history of what happened during the incident is exactly what you will want afterwards. When to Reset, Restore, or Revert covers the mechanics; the revert of the bad commit belongs in history either way.

The deciding question

Ask one thing: can the old code run against the current database? If yes, roll back - it is faster and safer than any fix you will write under stress. If no, you are rolling forward, and the time to accept that is immediately, not after forty minutes of trying to make rollback possible.

The two habits that keep the rollback door open are boring ones: backward-compatible migrations, and releases structured so going back is one command. Both are decided on quiet days, which is the only time incident decisions ever get made well.

Server-Side Git Hooks Worth Running on Your Own Server

Wed, 21 Oct 2026 00:00:00 GMT

Local hooks (the kind in git hooks for Laravel projects) run on the developer's machine, which means they run only when the developer kept them installed. Server-side hooks run on every push, for everyone, no exceptions. When you self-host, they are one of the best reasons to - and one of the easiest ways to annoy your team if you overreach.

Three checks that earn their place

1. Block the secrets. A pre-receive hook scanning pushed commits for private keys, .env contents and common token shapes turns a secret got committed from an incident into a rejected push. Gitleaks or a few good regexes; the point is that the secret never lands in the repo's history at all, which is when cleanup is free.

2. Protect the default branch. Even with branch protection rules configured in the UI, a pre-receive or update hook rejecting direct pushes to main is the belt to the platform's suspenders - it still fires if someone widens a permission by mistake.

3. Refuse giant blobs. A 200MB binary committed once lives in every clone forever. Rejecting pushes with files over a sane limit (100MB is GitHub's line; yours can be lower) pushes large assets to Git LFS before they become permanent.

The restraint that keeps them tolerable

A rejected push interrupts someone mid-flow, so every hook owes them three things:

A fast answer. A hook that scans ten thousand commits on every push will be bypassed, not loved. Check the pushed range, not all of history.
A message that says how to fix it. "Push rejected: possible secret in src/config/legacy.php (line 41). Remove it, rewrite the commit, see ." A bare "rejected" teaches people to fear the server; a clear one teaches them the rule.
A real escape hatch. False positives happen - a test fixture that looks like a key, a legitimate big file. Someone on the team should be able to bypass with a reason, and that bypass should be logged, not forbidden.

Start with the secret scanner; it has the best ratio of one-time setup to incidents prevented. Add rules the way you add tests: when the failure actually happens, not in anticipation of every imaginable one.

Five git config Settings Worth Changing Today

Wed, 21 Oct 2026 00:00:00 GMT

Git ships with conservative defaults that made sense in 2005 and mostly survive on inertia. Five one-line changes make day-to-day mistakes structurally harder. Each takes ten seconds; none changes anything you have already committed.

1. pull.ff=only - pulls that cannot create surprise merges

git config --global pull.ff only

A plain git pull on a diverged branch creates a merge commit you did not ask for. With this setting, a pull either fast-forwards cleanly or stops and tells you to decide - rebase or merge - consciously. It converts a common accident into a deliberate choice.

2. fetch.prune=true - remotes that tidy themselves

git config --global fetch.prune true

Deleted remote branches normally haunt your git branch -a forever. Prune makes every fetch drop the local copies of branches that no longer exist on the remote, so the list you see is the list that is real.

3. rerere.enabled=true - resolve each conflict once

git config --global rerere.enabled true

Reuse recorded resolution: Git remembers how you resolved a conflict and replays it the next time the same conflict appears - a gift for anyone who rebases long branches or keeps a fork in sync. Our rerere guide shows the workflow in full.

4. push.autoSetupRemote=true - no more --set-upstream

git config --global push.autoSetupRemote true

Pushing a new branch stops failing with the "no upstream" lecture and just sets the upstream. Modern Git (2.37+) has this built in; it removes the most copy-pasted error message in the tool.

5. init.defaultBranch=main - the name you expect

git config --global init.defaultBranch main

New local repositories start on main, matching every modern host, instead of falling back to the legacy default and forcing a rename later.

One caveat: these are personal settings, not team policy. Anything the team must share belongs in documentation, hooks, or CI - a config value only travels as far as your laptop. For the shared layer, git hooks for Laravel projects is the right tool.

Set all five now; your future self, mid-conflict, will be quietly grateful.

Shallow and Partial Clones: Faster CI Without Losing Your Mind

Wed, 21 Oct 2026 00:00:00 GMT

Every CI run starts the same way: clone the repo. As the repo grows - years of history, old assets, deleted binaries that still live in the past - that clone quietly becomes the slowest part of the pipeline. The fix is usually two flags, but they come with sharp edges worth knowing about.

Shallow clone: --depth

A shallow clone downloads only the most recent commits:

git clone --depth 1 https://github.com/your-org/your-app.git

No history, no old blobs, a fraction of the download. For a pipeline that installs dependencies and runs PHPUnit, history is dead weight. GitHub Actions spells the same idea fetch-depth: 1 in actions/checkout; GitLab CI calls it GIT_DEPTH: "1".

Partial clone: --filter

A partial clone keeps all commits but skips blobs until they are actually needed:

git clone --filter=blob:none https://github.com/your-org/your-app.git

You get the full commit graph instantly; file contents are fetched on demand from the remote. This suits developer machines working on a huge repo more than CI - CI usually wants no history at all, which is the shallow clone's job.

The two gotchas

Tags and versions. A shallow clone may not include tags, which breaks tooling that derives a version from git describe or the nearest tag. If your deploy step stamps a version this way, either fetch tags explicitly (git fetch --tags --depth 1 or fetch-depth: 0 in Actions) or pass the version in from the pipeline. Our post on deploying with tags covers the tagging side.

Anything that diffs against the past. A changelog generated from history, git blame, an incremental static-analysis baseline, git log for a "what changed since last deploy" note - all of these silently degrade or fail on a depth-1 clone. The rule of thumb: if a step reads history, give it history; if a step only builds and tests, shallow is safe.

Measure first: time the checkout step of your slowest pipeline. If it is more than thirty seconds, a shallow clone is likely the cheapest speedup available to you - one line in the CI config, no code changes, every run a little faster.

Shipping a Hotfix Without the Drama

Wed, 21 Oct 2026 00:00:00 GMT

Production is broken and main has moved on - it contains three half-finished features that cannot ship today. The hotfix question is how to patch what is live without dragging main along. The answer is short: branch from the tag that is running, fix there, tag, deploy, merge back.

The walkthrough

git switch -c hotfix/invoice-total-rounding v1.14.0
# fix the one thing, with a test
git tag -a v1.14.1 -m "v1.14.1"
git push origin hotfix/invoice-total-rounding v1.14.1

Deploy v1.14.1 exactly the way you deploy everything else - Deploy With Tags, Not Branches applies even more under pressure, because "what is running" must have one unambiguous answer during an incident.

Then bring the fix home so the next regular release does not reintroduce the bug:

git switch main
git merge hotfix/invoice-total-rounding

Discipline under pressure

The rules that keep a hotfix small:

One fix. A hotfix branch is not a vehicle for the cleanup you noticed on the way in. Everything else goes into a normal PR tomorrow.
The test comes too. If the bug was reachable once, it is reachable again; the test is what makes "fixed" verifiable rather than hoped. This is the moment the first CI pipeline earns its keep - the hotfix PR gets the same green check as everything else.
No shortcuts around review. One approval, even a two-minute one, catches the mistake made at speed. Branch protection should have no "except hotfixes" hole; it should have a fast path through the normal gate.

If the fix is bigger than a hotfix

When the honest assessment is "this needs a day of work," stop calling it a hotfix and decide rollback or roll-forward instead. A rollback buys the day cleanly. The worst outcome is the middle path: an ever-growing hotfix branch that is secretly a release, deployed with none of the care a release gets.

Branch from the tag, fix one thing, tag, merge back. Written down and rehearsed once, the next production bug is a procedure, not an event.

Shortening Git With Aliases

Wed, 21 Oct 2026 00:00:00 GMT

You will type git status ten thousand times this year. Aliases turn the frequent commands into a few keystrokes, and the long flag combinations into something you no longer have to remember.

Setting them

git config --global alias.st status
git config --global alias.sw switch
git config --global alias.br branch

git st now runs git status. Aliases live in your ~/.gitconfig under [alias] - plain text, editable directly when you outgrow the command line form.

The ones that earn their keys

The graph view from the history guide, as two letters:

git config --global alias.lg "log --oneline --graph --decorate --all"

A safe undo for the commit you just made:

git config --global alias.undo "reset --soft HEAD~1"

And the fixup workflow paired with autosquash:

git config --global alias.fixup "commit --fixup"

git fixup abc1234 marks a commit as belonging to an earlier one; git rebase -i --autosquash main then folds it in automatically. That pair is the fastest way to keep a branch tidy as you go instead of in one pass before review.

Anything beyond one git command gets a ! prefix to run through the shell - alias.today = "!git log --since=midnight --oneline".

The honest limits

Aliases are yours, not the repo's. They do not exist on a teammate's machine, in CI, or on a fresh laptop until you recreate them - so scripts, hooks and documentation must always use the full commands, and the aliases belong in your dotfiles backup, not in project tooling. And keep the list short: an alias you have to look up defeats the point. Five you use hourly beat fifty you typed once.

If a command pair keeps recurring across the whole team, that is a sign it wants to be documentation or a shared script - not forty personal aliases converging on the same idea.

Signed Commits: When Your Team Should Bother

Wed, 21 Oct 2026 00:00:00 GMT

A commit's author line is a text field anyone can set. Signing replaces "trust the name" with "trust the key". Whether your team needs that depends on what the repo protects.

The cheap version: sign with your SSH key

No GPG setup anymore — git signs with the SSH key you already push with:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Add the same public key to your git host as a signing key and your commits show as verified.

When it earns the setup

Repos whose history feeds audits or compliance, where "who actually wrote this" needs an answer.
Open source or vendor code others build on, where a forged author line is a real supply-chain risk.
Teams with contractors coming and going, where key rotation is easier to reason about than usernames.

When to skip it

A private repo for a two-person team that reviews everything anyway gains little. Signing proves authorship of the commit, not quality of the code — review is still the control that matters.

If you adopt it

Turn on the host's "require signed commits" only after everyone signs comfortably. Flipping it early just teaches people to bypass the rule.

Small Pull Requests Get Reviewed Faster

Wed, 21 Oct 2026 00:00:00 GMT

A 1,500-line pull request does not take ten times longer to review than a 150-line one. It takes longer than that, because nobody starts it. Reviewers see the line count, decide they need a free afternoon they do not have, and the PR sits. Small PRs break that cycle.

Why big PRs stall

Three things happen with a large diff:

Reviewers postpone it, so feedback arrives days late, after you have mentally moved on.
When the review finally happens, it is shallow - nobody can hold 40 files in their head, so real bugs hide in the middle of the diff.
Merges get riskier, because a PR that touches everything conflicts with everything.

A PR under a few hundred lines gets read the day it opens, and it gets read properly.

Splitting a Laravel feature

Take a typical feature: a migration, a model, a controller, routes, a form request, views, tests. That feels atomic, but it usually splits cleanly:

Migration and model first - the schema is reviewable on its own.
The read path next - list and show endpoints with their tests.
The write path last - create, update, delete, and validation.

Each PR is deployable, each review is quick, and if the write path turns out to be the wrong design, you have not merged it yet. If later PRs depend on earlier ones, use stacked branches: branch the second PR off the first, and retarget it to main once the first merges.

Keeping PRs small day to day

One idea per PR. If the description needs an "and also", it is two PRs.
Split mechanical changes (a rename across 30 files, a Pint run) from behavioral ones, so the behavioral diff stays readable.
Tidy commits before opening the PR so the reviewer reads your intent, not your process - see Tidying Commits Before You Open a Pull Request.
Write a description that says what to look at first - Writing a Good Pull Request Description covers that.

The habit compounds: reviewers who trust your PRs to be small stop dreading them, and the whole team's queue moves. Pair it with the review-side habits in Code Review Habits That Actually Catch Bugs and the review round trip gets short enough to feel like pair programming at a distance.

Squash Merge or Merge Commit: Choosing at the PR Button

Wed, 21 Oct 2026 00:00:00 GMT

The pull request is approved and the button offers a choice: merge commit, squash, or rebase. The code landing on main is identical either way; what changes is the story main tells afterwards.

Merge commit: keep the branch as it was

A merge commit preserves every commit on the branch plus a marker joining it to main. Choose it when the branch's commits are already clean - tidied with an interactive rebase, each one a real step. Main keeps the full context, and git log --graph shows the branch as a readable bubble.

The cost: if the branch was full of "wip" and "fix", all of that lands on main forever.

Squash: the branch becomes one commit

Squashing collapses the whole PR into a single commit on main. Choose it for the common case: a feature branch with exploratory, fix-as-you-go commits whose value was the journey, not the record. Main gains one commit per piece of work, which is exactly the granularity a changelog and a git log --oneline scan want.

Two things make squashing work well. Write the squash commit message properly - it is the only message main will keep, so give it the conventional prefix and a real summary. And delete the branch after merging: pushing more commits to a branch that was already squash-merged produces a follow-up PR full of commits main already has, because the squashed commit shares no history with them.

Rebase merge: linear, commit by commit

Rebasing at merge replays the branch's commits onto main one by one, no merge bubble. Choose it for small PRs that are already clean and where the team wants a strictly linear main. It asks the most of the branch - every commit lands verbatim, "fix typo" included - so it only suits branches that were tidied first.

A rule a small team can keep

Branch is messy (the usual case): squash, write a real message, delete the branch.
Branch is clean and the steps matter: merge commit.
Branch is clean and tiny: rebase is fine, but squashing it is fine too.

Agree on it once, write it in the README, and the choice stops costing a thought per PR.

SSH Keys for Git Access: Set Up Once, Push Forever

Wed, 21 Oct 2026 00:00:00 GMT

Every push to a self-hosted Git server starts with the same question: who are you? SSH keys answer it without passwords - but only if they are set up right, and "set up right" takes about five minutes once.

One modern key

ssh-keygen -t ed25519 -C "stefan@work-laptop"

ed25519 is the current default: short keys, fast verification, no size decisions. The comment (-C) is a label, not a login - use the machine or purpose, so that when you revoke a lost laptop's key next year you can tell which one it was. A passphrase on the key is worth it; the SSH agent means you type it once per session, not once per push.

Hand the public half to the server

The file ending in .pub is the one you share. On a self-hosted server it goes into the user's account in the web UI (or authorized_keys on a bare setup). The private half never leaves your machine - a server asking for it is a server you should stop using.

Then test:

ssh -T git@yourgit.example.com

A greeting means you are done; "Permission denied (publickey)" means read on.

When it does not work

Three causes cover almost every failure:

The agent is not offering the key: ssh-add -l lists what the agent holds; ssh-add ~/.ssh/id_ed25519 adds it.
SSH is offering the wrong key first. Some servers drop the connection after a few failed offers. Pin the right one in ~/.ssh/config:

Host yourgit.example.com
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

The remote URL is HTTPS while your account expects SSH (or the reverse). Check with git remote -v - the fix is changing the URL, and if a fork or second server is involved, the two-remote layout from Keeping a Fork in Sync keeps them straight.

Per-machine, not per-person

Treat keys as belonging to machines, not to you: laptop key, desktop key, CI deploy key. Revoking a device is then a one-line delete on the server, and the audit log of who pushed what stays meaningful - which matters more once branch protection makes pushes consequential.

Set it up once per machine, and the question "who are you?" stops appearing in your day entirely.

Staging Changes in Hunks With git add -p

Wed, 21 Oct 2026 00:00:00 GMT

You sat down to fix a validation bug, and forty minutes later the file also contains a renamed method, a corrected comment, and an unrelated typo fix. git add app/ would bake all of that into one commit. git add -p is how you split it instead.

Stage by hunk, not by file

git add -p app/Http/Requests/StoreInvoiceRequest.php

Git walks through the file's changes hunk by hunk and asks what to do with each:

Stage this hunk [y,n,q,a,d,s,e,?]?

The keys worth memorizing:

y - stage this hunk
n - skip it (stays in your working tree)
s - split the hunk into smaller pieces, when Git's chunk is too coarse
e - edit the hunk manually, for the cases splitting cannot reach
q - stop; everything already chosen stays staged

Two passes and you have the validation fix staged as one commit while the rename waits in the working tree for its own. This is the mechanical skill underneath Tidying Commits Before You Open a Pull Request - clean commits are much easier to build at staging time than to reconstruct afterwards.

Why it matters beyond tidiness

Partial staging is also a review tool. Going hunk by hunk forces you to look at every change once more before it is committed - the same effect as reviewing your own pull request, but earlier and cheaper. The leftover dump() rarely survives a git add -p pass.

And it keeps each commit revertable. When the typo fix and the validation fix are separate commits, rolling back a bad one with git revert does not take the good one with it - the payoff promised in When to Reset, Restore, or Revert.

The same idea elsewhere

git checkout -p, git restore -p, and git stash -p all speak hunk-level too: discard part of a file, or stash only the experiment while keeping the fix. Once the hunk way of thinking clicks, half of Git's plumbing turns out to support it.

One honest caveat: staging part of a file means the committed state is one you never ran. For risky splits, git stash --keep-index before testing stashes the unstaged half so you can run the test suite against exactly what you are about to commit.

Stashing Changes in Git Without Losing Them

Wed, 21 Oct 2026 00:00:00 GMT

You are halfway through a change when something more urgent lands: a failing deploy, a review to run, a bug on main. Committing half-work pollutes history; stashing shelves it exactly as it is.

Shelve and return

git stash            # shelve tracked changes, clean working tree
git stash pop        # bring the latest stash back and drop it from the list

Two additions cover most real cases. Untracked files are left behind by default, and a new factory or migration is usually untracked:

git stash -u

And a message, because "WIP on main" tells you nothing next week:

git stash push -u -m "invoice pdf: half the template"

The pile

git stash list
git stash show -p stash@{1}
git stash apply stash@{1}

pop applies and drops; apply applies and keeps. Reach for apply when the same shelved work might go on more than one branch, or whenever you are not sure - a stash you keep costs nothing, a stash you dropped and needed is gone.

Stash part of the mess

Sometimes half the working tree belongs to the urgent thing and half to your paused work. Pathspecs split them:

git stash push -m "just the config tweak" config/queue.php .env.example

Only those paths are shelved; the rest of the mess stays where it was.

When the stash grew into real work

A shelved experiment that turned out to be the fix does not belong on top of whatever your working tree has become. Give it its own branch:

git stash branch fix/invoice-pdf stash@{0}

That creates the branch from the commit you stashed on, applies the stash there, and drops it.

The honest warnings

Stashes are local. They are never pushed, so they are not a backup and your self-hosted remote never sees them. Anything you would miss should be a commit on a branch.
pop can conflict if the tree moved on. It works like a merge: resolve, and the stash stays in the list if the pop fails.
Stashes fossilize. If git stash list shows entries from last month, they are todos in disguise - apply them to a branch or drop them.

If the context switch is a review rather than an emergency, a worktree beats a stash entirely: the working tree stays untouched and the PR runs next door. But for the five-minute interruption, stash is the right size of tool.

Submodules: When a Laravel Team Actually Needs One

Wed, 21 Oct 2026 00:00:00 GMT

Someone suggests a submodule the first time two apps need the same code. It sounds like sharing; what it actually does is pin a commit of one repository inside another. Sometimes that is exactly what you want. For PHP code, it usually is not.

Why they have a reputation

A submodule is a second repository with its own history, and Git only records which commit it sits on. That design creates the daily friction:

A plain git clone or git pull does not fetch submodule contents - the directory sits empty until git submodule update --init --recursive.
The submodule's HEAD is detached by default, so committing inside it needs the same care as any detached state.
Updating means committing in the submodule, pushing it, then committing the new pin in the parent - two commits, two pushes, and a parent repo that is wrong if either is forgotten.
CI, deploy hooks and new teammates each get to discover all of this once.

The Laravel answer for shared code

If the shared thing is PHP - a domain package, SDK wrappers, shared DTOs - make it a Composer package instead. A private package on Satis or Private Packagist, or even a path repository while it is small, gives you real versioning: composer update, semver constraints, and a lock file that says exactly what runs where. That is strictly better than a pinned commit with no version number, and every Laravel developer already knows the workflow.

When the submodule is right

The honest cases:

Shared non-PHP content - infrastructure definitions, deployment config, a docs site - where Composer cannot carry it anyway.
Vendoring a third-party project you patch and need to track against upstream, where forking plus subtree is heavier than the pin.
You genuinely want an exact, reviewable pin with no registry involved: the parent repo's history shows every bump as a normal commit.

If you take one on

git clone --recurse-submodules git@yourserver:app.git
git config submodule.recurse true

The clone flag populates the submodule from day one; the config makes ordinary pulls update it too. Both remove the class of mistake that gives submodules their name, because the empty-directory surprise is the one people hit first.

The rule of thumb: PHP code becomes a package; everything else is allowed to be a submodule - with the flags set before the first teammate clones it.

Switching Branches With git switch (and Why checkout Still Works)

Wed, 21 Oct 2026 00:00:00 GMT

For years git checkout did at least four different jobs: switching branches, creating branches, restoring files, and detaching HEAD. One command, four meanings, and a classic footgun - git checkout . throws away uncommitted work, which surprises everyone exactly once.

Since Git 2.23 the jobs are split into two commands with names that say what they do.

git switch is for branches

git switch main                 # go to an existing branch
git switch -c feature/invoices  # create a branch and move to it
git switch -                    # back to the branch you were just on

The -c flag replaces git checkout -b, and git switch - is the handiest of the lot when you bounce between a feature branch and main to re-run a test suite. If you have uncommitted changes that would be overwritten, switch refuses instead of silently discarding them - the same safety checkout had, but without the file-restoring ambiguity.

git restore is for files

git restore app/Models/Invoice.php   # discard uncommitted changes to a file
git restore --staged config/mail.php # unstage, keeping the edits

Both remain destructive-or-not in exactly the ways covered in When to Reset, Restore, or Revert - the split just makes the intent obvious when you read a command back in your shell history.

What you can keep doing

Nothing was removed. git checkout still works everywhere it used to, and plenty of teams never bothered switching habits. The reason to adopt the newer pair is readability: git switch -c feature/x tells the next person (and future you) exactly what happened, while git checkout always needs a second look to see which of its four jobs it was doing.

Worth knowing alongside this: Stashing Changes Without Losing Your Place for the case where you want to switch branches but are not ready to commit, and git switch --detach <commit> for deliberately inspecting an old commit - the tamer cousin of accidentally landing in a detached HEAD.

Tagging Releases Properly in Git

Wed, 21 Oct 2026 00:00:00 GMT

git tag v1.5.0 takes three seconds and produces the weaker of Git's two tag types. For anything you will deploy, reference in a changelog, or bisect against later, take the extra flag.

Lightweight vs annotated

A lightweight tag is just a name pointing at a commit - a branch that never moves. An annotated tag is a real Git object: it carries its own message, the tagger's identity and the date:

git tag -a v1.5.0 -m "v1.5.0: invoice PDFs, queue retry fix"

That message is the difference. Six months from now, git show v1.5.0 on an annotated tag tells you what the release was; on a lightweight one it shows whatever commit happened to be tagged, with no context.

Tag what you deploy

The tag should mark the commit that actually went out. On a merge-based flow that is the merge commit on main - not the last feature commit on the branch, and not "roughly that week". Tagging anything else makes git bisect between releases and git log v1.4.0..v1.5.0 quietly wrong, and those two commands are the whole point of having tags.

Push them deliberately

Tags do not travel with ordinary pushes:

git push origin v1.5.0

Push the one tag by name. git push --tags sends every local tag, including the throwaway markers you made for yourself - keep that one for the rare day you actually mean it.

Optional: signed tags

git tag -s signs the tag with your key, so the release record is verifiable as yours. For a small team shipping to their own server it is usually more ceremony than threat model; for anything customers or auditors pull, it is the same calculation as signing commits - cheap with SSH keys, worth it when provenance matters.

Annotated tags plus the changelog habit are the whole release ritual: the tag marks what shipped and says it in a sentence, the log between tags writes the notes, and git bisect between two tags finds the commit that broke the build.

The Reflog: Undoing Almost Anything in Git

Wed, 21 Oct 2026 00:00:00 GMT

Git rarely loses commits; it loses your pointer to them. The reflog is the record of everywhere HEAD has been, and it turns most "I destroyed everything" moments into a two-minute fix.

Find where you were

git reflog

Every line is a position HEAD held, newest first: checkouts, commits, resets, rebases. Find the entry just before the mistake — its message usually names the operation that went wrong.

Go back there

git reset --hard HEAD@{2}

Or, safer, put a branch on the good position first and look at it before resetting anything:

git branch rescue HEAD@{2}

The classic recoveries

git reset --hard one commit too far: the "lost" commit is in the reflog, reset back to it.
Deleted branch you still needed: git reflog, find the last commit the branch pointed at, git branch the-name <hash>.
Rebase gone wrong: the reflog holds the branch's pre-rebase position as HEAD@{n} from before the rebase started.

The limits

The reflog is local and expires (90 days by default for reachable entries). It saves you from your own commands, not from a disk dying — that is what the remote is for. And uncommitted work that was never staged is genuinely gone; the reflog only tracks commits.

When in doubt, git branch rescue first. A branch you delete after inspecting costs nothing.

Interactive Rebase: Tidying Commits Before Review

Wed, 21 Oct 2026 00:00:00 GMT

A working branch grows honest mess: "wip", "fix", "actually fix the fix", a debug commit with a dump in it. Reviewers deserve better, and interactive rebase is how the branch tells a clean story before they see it.

Open the editor on your own commits

git rebase -i main

Git lists the commits your branch adds, oldest first, each marked pick. Reorder the lines to reorder the commits; change the verb to change what happens to each.

The four verbs that matter

reword - keep the change, rewrite the message. For every commit whose message you would not say out loud.
squash - fold a commit into the one above it and combine the messages. For "and the test for it" commits.
fixup - fold in and discard the message. The typo fixes and "forgot a semicolon" commits disappear into the commit they belong to, which is exactly where they belonged all along.
drop - delete the commit. The debug dump goes here.

Save, and Git replays the branch with your edits. If a squash or reorder conflicts, resolve as usual and git rebase --continue; git rebase --abort returns everything to how it was.

The two rules

Only rewrite commits nobody else has. Interactive rebase rewrites history, so it belongs to your own unpushed branch - the same boundary as plain rebase and reset.
If the branch was already pushed, the tidy version goes up with git push --force-with-lease, never bare --force - the lease refuses if a reviewer pushed anything meanwhile.

When it goes wrong

A rebase that produced nonsense is not lost. The reflog remembers the branch's pre-rebase position; git branch rescue HEAD@{n} on that entry, inspect, and try again. Tidying is safe precisely because the escape hatch is reliable.

The goal is not a fake-perfect history. It is a branch where every commit is one idea, described once - the version of the work you would have written if you had known the ending from the start.

Trunk-Based Development on a Small Laravel Team

Wed, 21 Oct 2026 00:00:00 GMT

Long-lived feature branches feel safe and bill you later: the two-week branch that takes a day to merge, and the merge nobody wants to re-run. Trunk-based development is the alternative that works well for small teams.

The rules, sized for a small team

Everything targets main. Branches live hours to a couple of days, never weeks.
Main always runs: tests pass, migrations apply, the app boots.
Review is quick and small, because the changes are small.

Half-done work still merges

The objection is always "the feature is not finished". Merge it anyway, behind a flag. In Laravel that is a config entry or a Feature::active() check, not a branch:

if (config('features.new_billing')) {
    // new flow
}

Delete the flag when the feature ships. A flag you forget is cheaper than a branch you rebase for a month.

What it buys

Conflicts stay small because diffs stay small. Main is deployable any day, so the git-push deploy from a tag or from main stops being an event. And code review gets read, because there is finally little enough of it.

Start with the rule that matters most: nothing lives on a branch longer than two days.

What Not to Commit in a Laravel Project

Wed, 21 Oct 2026 00:00:00 GMT

A Laravel repo should hold the recipe, not the kitchen. The generated and environment-specific parts belong elsewhere.

The .gitignore that covers it

/vendor
/node_modules
.env
.env.backup
.phpunit.result.cache
/public/build
/public/hot
/storage/*.key
/storage/logs/*.log
Homestead.json
Homestead.yaml

Laravel's default .gitignore ships most of this. The ones people add by hand are the environment files and the editor/OS noise (.idea, .DS_Store — those belong in your global gitignore, not the project's).

Why each one stays out

vendor/ and node_modules/ are rebuilt by composer install and npm ci from the lock files — which you do commit.
.env is per-machine by definition and carries secrets. Commit .env.example with the keys and empty values instead.
public/build is Vite output; it gets rebuilt on every deploy.
storage/*.key and logs are runtime state, different on every server.

Already committed something?

git rm --cached -r vendor stops tracking it without deleting your local copy, then commit the removal. If the file carried a secret, that is not enough — the history still has it, and the rotate-first routine applies.

What to Do in a Detached HEAD

Wed, 21 Oct 2026 00:00:00 GMT

"You are in 'detached HEAD' state" reads like a warning that something broke. Nothing broke. Git is saying your HEAD - the pointer that normally sits on a branch - is pointing directly at a commit. Everything works; the only real question is what happens to commits you make here.

How you got here

The usual doors in:

git checkout 3357a04      # inspect an old commit
git checkout v1.4.0       # look at exactly what a tag shipped

Bisect and rebase also park you here on purpose. Checking out a tag to reproduce a bug against the exact deployed code is a completely ordinary reason to be detached.

Looking is free, committing is fine, leaving is the catch

Read files, run the test suite, boot the app - the working tree is real. You can even commit. The catch: no branch points at those new commits, so when you switch away they become unreferenced, and the only thing that will ever find them again is the reflog.

So the rule is simple. The moment you make a commit you want to keep, give it a branch:

git switch -c fix/reproduce-invoice-bug

That is the whole fix. HEAD now points at a normal branch holding your work, and the detached state is over.

If you already switched away

The commits are not gone; they are unreferenced. Find the hash you were on:

git reflog

The recent checkouts are right at the top. Put a branch on the hash:

git branch rescue 3357a04

The reflog keeps these entries for 90 days by default, so "I detached, committed, and switched away an hour ago" is a two-command recovery, not a lost afternoon.

The habit

Treat detached HEAD as a reading room, not a workspace. Look all you want; the instant you write something worth keeping, git switch -c before you do anything else - especially before switching branches, which is the moment the work becomes findable only through the reflog.

If you find yourself detaching often just to run someone else's PR without disturbing your working tree, that is the job worktrees do without the detachment at all.

When to Reset, Restore or Revert

Wed, 21 Oct 2026 00:00:00 GMT

Git has three undo commands and they are not interchangeable. restore touches uncommitted work, reset moves your own branch, and revert undoes a commit that other people may already have. Picking by what you are undoing - and who has seen it - keeps undo boring.

Restore: uncommitted work

You edited a file and the change is wrong. It is not staged, not committed:

git restore app/Models/Invoice.php

Staged it by accident but still want to edit? Unstage without losing the edit:

git restore --staged app/Models/Invoice.php

Restore only reaches work that exists in some committed form. An edit to a file that was never committed anywhere is gone for good once restored away.

Reset: commits nobody else has

You committed on your branch, have not pushed, and want those commits back as working changes:

git reset --soft HEAD~1    # undo the commit, keep everything staged
git reset HEAD~1           # undo the commit, keep the changes unstaged
git reset --hard HEAD~1    # undo the commit and throw the changes away

Reset rewrites the branch, so it belongs to history only you have seen. If a commit is already on the shared remote, reset is how you end up force-pushing over a teammate's work.

Revert: commits everyone has

A commit is on main, the deploy from it broke invoices, and the team has pulled it:

git revert 3e39e4f

Revert adds a new commit that applies the inverse diff. History keeps growing forward, nobody re-pulls a rewritten branch, and git revert of the revert brings the change back when the fix is ready. On a Laravel app this pairs cleanly with rollback: revert the commit, run php artisan migrate:rollback if it carried a migration, deploy again.

The rule of thumb

Not committed: restore.
Committed, not pushed: reset.
Pushed: revert.

When the mistake is bigger than one commit - a wrong rebase, a reset too far - the reflog remembers where the branch was before any of it. And when you are about to undo something you are not sure about, git branch rescue first: a branch you delete after inspecting costs nothing.

Why Git Blame Is Not About Blame

Wed, 21 Oct 2026 00:00:00 GMT

The name is the worst thing about git blame. The command does not exist to find someone to fault; it exists to answer the question every developer asks twenty times a week: why is this line here?

From line to decision

git blame app/Models/Invoice.php

Every line comes back annotated with the commit that last touched it, the author and the date. The commit hash is the valuable part - follow it:

git show 8c6e7ec

Now you have the full diff, the commit message, and usually the pull request it came from. That chain - line, commit, message, PR - is the difference between staring at a strange condition and understanding the edge case it guards.

Two options earn their keep:

git blame -L 40,60 app/Models/Invoice.php   # just these lines
git blame -w config/queue.php               # ignore whitespace-only changes

-w matters more than it looks: without it, the last person to reindent a block "owns" every line in it.

Hide the reformat commit

Every repo has one: the day the whole codebase was reformatted, and blame started pointing every line at it. Git has a built-in answer:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Put the reformat commit's hash in .git-blame-ignore-revs, commit the file, and blame skips those revisions on everyone's machine. GitHub honours the same file in its blame view, so the fix works locally and in the browser.

When blame is the wrong tool

Blame shows the last commit to touch a line. To find when something appeared or disappeared entirely - a setting, a constant, a call - the pickaxe is better:

git log -S 'QUEUE_CONNECTION' --oneline -- config/queue.php .env.example

The culture part

Used as a name-and-shame tool, blame makes people defensive and teaches them to avoid touching old code. Used as a documentation tool, it does the opposite: the author of a line is the person most likely to remember the constraints behind it, and "what were we solving here?" gets a useful answer where "who broke this?" gets silence.

The habit to build is simple. When a line surprises you, blame it, read the commit, and ask about the decision - not the person.

Why You Should Force Push With --force-with-lease

Wed, 21 Oct 2026 00:00:00 GMT

If you rebase, squash or amend, you will eventually need to force-push. The question is never whether force-pushing is evil - it is whether the push can silently delete someone else's work. Plain --force can. --force-with-lease cannot.

The legitimate case

Your PR branch, reviewed once, now rebased onto current main with the fixups squashed in. The remote still holds the pre-rebase version, and the only way to update it is a force-push. That is fine: the branch is yours, and nobody should be building on it.

What --force actually says

git push --force

"Make the remote branch point here, whatever it points at now." If a teammate pushed a commit to your branch since your last fetch - a reviewer fixing a typo through the web UI is the classic way - that commit is gone from the branch, and nobody was asked.

What --force-with-lease says

git push --force-with-lease

"Make the remote branch point here, but only if it still points where my last fetch left it." The lease is your local record of the remote ref. If the remote moved - anyone pushed anything - the push is refused and nothing is overwritten. You fetch, look at what arrived, rebase onto it, and push again.

For another layer, --force-if-includes additionally checks that the remote's current commits are already part of what you are pushing, which catches some stale-reflog corner cases the lease alone misses.

The two rules that make it boring

Never force-push a branch other people build on. Main, release branches, long-lived feature branches: these get merges and reverts, not rewrites. Branch protection should simply forbid it there.
On your own short-lived branches, always --force-with-lease, never bare --force. Put it in muscle memory or in an alias, because the one time you reach for plain --force is the one time the remote had a surprise waiting.

If the worst already happened and a force-push ate a commit, it is recoverable: the commit still exists on the machine that made it, and that machine's reflog knows the hash. A git push <hash>:refs/heads/branch-name from there puts it back.

Writing a CONTRIBUTING.md People Actually Read

Wed, 21 Oct 2026 00:00:00 GMT

Most CONTRIBUTING.md files fail the same way: they are written for the maintainer's peace of mind, not the reader's goal. A new contributor - or a teammate joining the project, which is the same reader - wants three answers: how do I run this, how do I change it, and how do I get the change accepted. Write those, in that order, and stop.

1. Setup that actually works

The first section is the one that gets read: clone, install, run. For a Laravel app that is the composer install, .env setup (which our env files guide covers properly), migrations, and the one command that proves it works - php artisan serve, npm run dev, the test suite.

The test is brutal and simple: hand the repo to someone who has never seen it and watch. Every place they stop is a line your guide is missing. Do this once a year, because setup rots.

2. The workflow, concretely

Branch naming if you have a convention, what a pull request should look like (link your PR template if you have one), who reviews, and how long a review usually takes. That last one matters more than anything else in the file: "expect a first review within two working days" turns waiting from neglect into process.

Keep it to what a contributor does, not how the team philosophizes. Three paragraphs is plenty.

3. The bar for merging

What CI must pass, whether commits get squashed (see squash merge or merge commit), any style tooling that will reject the PR - Pint, ESLint, whatever runs. Contributors forgive strict rules; they do not forgive discovering them in a red CI run after pushing.

What to leave out

Code of conduct boilerplate in the same file. Worth having, worth its own file - GitHub surfaces CODE_OF_CONDUCT.md separately.
Architecture essays. Link the README or docs instead; a guide that takes twenty minutes to read gets zero minutes.
Rules nobody enforces. Each one teaches the reader that the file is decorative, and then they skip the real rules too.

A contributing guide is a promise: follow this and your work lands. Every line either keeps that promise shorter or makes it longer. Keep the short ones.

Writing a Pull Request Description People Actually Read

Wed, 21 Oct 2026 00:00:00 GMT

Reviewers decide how carefully to read from the description. A blank one says "good luck"; a wall of text says the same thing louder. Three short sections cover almost every PR.

What changed

One or two sentences, no file list — the diff already shows files. "Adds a queued job that re-sends failed webhook deliveries with backoff" is enough.

Why

The part that saves the reviewer a Slack message. Link the ticket if there is one, otherwise say what was broken or missing. "Deliveries failed silently when the endpoint returned 5xx, and clients had no way to replay them" is a reason; "requested changes" is not.

How to see it working

The step everyone skips and the one reviewers want most: the command to run, the page to open, the seed data to create. On a Laravel app that is usually a route to hit, an artisan command, or a test to run:

php artisan test --filter=WebhookRetryTest

Keep it short on purpose

If the description needs paragraphs, the PR probably needs splitting. Small PRs with three honest sections get read, get real comments, and merge while the context is still warm.

Writing a Postmortem That Actually Changes Something

Wed, 21 Oct 2026 00:00:00 GMT

The deploy broke billing for forty minutes. Everyone is relieved it is over, everyone is tired, and now someone has to write the postmortem. The temptation is a document that says "a mistake happened, we fixed it, we will be more careful." That document is worse than none: it performs learning without doing any.

A postmortem that changes things has three sections, and each has a rule.

Timeline: facts, in order, with timestamps

When did monitoring fire, who saw it, what did they try, when did recovery start. Written from logs and chat history, not memory - memory edits itself within hours. The timeline is where you discover the real story: the alert that fired twenty minutes before anyone looked, the rollback that took fifteen minutes because nobody remembered the command (which is why rollback or roll forward exists as a pre-made decision, not an improvised one).

Rule: no judgments in the timeline. "Deployed v2.3.1 at 14:02" is a fact. "Deployed carelessly" is a verdict, and verdicts here make people defensive before you reach the part that matters.

Contributing factors: plural, and never a person's name

"Stefan merged the bad migration" is not a cause; it is a scapegoat. The contributing factors are the things that made the mistake easy and its blast radius large: migrations deploy without a dry run, the billing smoke test only runs hourly, one person holds the rollback knowledge. Any of these could bite a different person next week, which is exactly why they are the fixable layer.

Rule: if a factor cannot be assigned to a system, a process or a missing safeguard, keep digging.

Actions: owned, dated, small

Every action has one name and one date. "Improve testing" is a wish; "Amira adds a billing smoke test to the deploy pipeline by Nov 7" is an action. Three real actions beat ten aspirational ones - and they go in the tracker, not just the document, because a postmortem action without a ticket is a hope.

Rule: review the actions at the next incident review or team meeting. An action that slips twice gets escalated or honestly dropped; silently forgotten is the one outcome that teaches the team postmortems are theater.

Write it within two days, share it where everyone can read it, and thank the people named in the timeline - they are the ones who told you the truth.

Zero-Downtime Deploys for Laravel, Explained Simply

Wed, 21 Oct 2026 00:00:00 GMT

The naive Laravel deploy is git pull on the live directory, and it has a window where the code is half-old, half-new - composer autoloads one version, the templates reference another, and a visitor in that second gets a broken page. Zero-downtime deploys remove the window with one idea: never change the directory the web server is looking at.

Releases and one symlink

The structure, used by every deploy tool worth using:

/var/www/app/
  releases/
    20261020-141122/
    20261021-093015/
  current -> releases/20261021-093015
  shared/
    .env
    storage/

Each deploy is a full checkout into a new timestamped directory. Composer install, artisan config:cache, asset builds - all happen there, while current still points at the previous release and the site keeps serving it. The switch is a single atomic operation: repoint the current symlink. If anything is wrong, point it back - rollback takes one second because the old release directory is still intact.

Two things must live outside releases: .env and storage/. Symlink them in from shared/ so every release uses the same environment and the same uploaded files.

Migrations are the hard part

Code swaps are easy; databases cannot be symlinked back. The rule that keeps deploys reversible: every migration must work with both the old and the new code. Adding a column is fine. Renaming one is not - do it as three deploys (add new, backfill and dual-write, drop old). Run php artisan migrate --force before the symlink swap, so the schema is ready for the release that is about to go live.

The queue and scheduler

Laravel queues hold serialized jobs, so after the swap, restart the workers (artisan queue:restart) or they keep running the old code from memory. The scheduler needs no restart - cron resolves through current on each run.

That is the whole shape: build beside, switch atomically, migrate compatibly, restart workers. Whether you script it yourself or adopt a tool, Deploy Laravel With Git Push covers the pipeline around it, and Deploy With Tags, Not Branches decides what each release directory should contain. A deploy your users never notice is not luxury - it is just structure.

Reviewing Pull Requests With Git Worktrees

Tue, 20 Oct 2026 00:00:00 GMT

Reviewing a pull request properly means running it, not just reading the diff. Switching your working copy back and forth costs your uncommitted state every time. Worktrees sidestep that.

Check out the PR next to your work

git fetch origin
git worktree add ../myapp-pr-42 pr-42-branch

You get a second directory on the PR branch while your main checkout stays exactly as it was.

Give it its own environment

A Laravel app needs more than the code:

cd ../myapp-pr-42
composer install
cp ../myapp/.env .env

Then change what must not clash: APP_URL and port if you serve both at once, and DB_DATABASE to a throwaway database so the PR's migrations do not touch your dev data:

php artisan migrate --seed
php artisan serve --port=8001

Tear it down cleanly

git worktree remove ../myapp-pr-42

The branch stays until you delete it; the directory and database go.

When it pays

One PR a month is fine to stash and switch. A team merging daily needs the review to be cheap, and cheap means the PR runs in its own directory while your own work never moves.

Deploying a Laravel App With Git Push

Mon, 19 Oct 2026 00:00:00 GMT

Self-hosting your git and your app on the same box has a nice property: a push can be the deploy. You need a bare repository and one hook.

The bare repo

git init --bare /srv/git/myapp.git

Add it as a remote on your laptop and push a branch you deploy from, for example main.

The post-receive hook

/srv/git/myapp.git/hooks/post-receive, made executable:

#!/bin/bash
set -e
APP=/var/www/myapp
git --work-tree=$APP --git-dir=/srv/git/myapp.git checkout -f main
cd $APP
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

checkout -f syncs the working tree to the pushed commit. The artisan steps are the boring, repeatable part of every Laravel release.

Keep it honest

Run the hook as a user that owns /var/www/myapp but cannot sudo.
migrate --force runs unattended, so only push migrations you have tested against a copy of production data.
If the hook fails, the push still lands in the repo; redeploy by pushing an empty commit or rerunning the hook on the server.

This is one step above "SSH in and pull". When you outgrow it — zero-downtime releases, rollbacks, multiple servers — that is the point where a real pipeline earns its keep, not before.

A Secret Got Committed. Now What?

Sun, 18 Oct 2026 00:00:00 GMT

It happens: .env, an API key, a database password ends up in a commit. The fix is the same every time, and the order matters.

1. Rotate the secret first

Deleting the file from git does nothing while the key still works. Assume anything committed is public, even in a private repo: clones, forks and CI caches all copy it. Revoke or rotate the credential at the provider before touching the repository.

2. Scrub the history

Once the old key is dead, remove it from history so the repo stops carrying it. git filter-repo is the tool that works:

pip install git-filter-repo
git filter-repo --path .env --invert-paths

This rewrites every commit, so force-push and have the team re-clone. A commit hash they still hold can resurrect the file.

3. Stop it happening again

.gitignore the file and commit a .env.example with the keys but no values.
Laravel reads real values from the environment, so nothing secret needs to be in the repo at all.
Turn on your host's push protection or run a pre-commit scan so a key gets caught before it lands.

The short version

A scrubbed repo with a live key is still a breach. A rotated key with an ugly history is just housekeeping. Rotate first.

Git Hooks That Earn Their Place on a Laravel Project

Sat, 17 Oct 2026 00:00:00 GMT

Hooks live in .git/hooks, which Git does not version. Point core.hooksPath at a folder in the repo so the whole team runs the same ones:

git config core.hooksPath bin/git-hooks

pre-commit: fix style before it lands

Run Laravel Pint against the staged PHP files only, so the check stays fast:

#!/bin/sh
files=$(git diff --cached --name-only --diff-filter=ACM -- '*.php')
[ -z "$files" ] && exit 0
echo "$files" | xargs ./vendor/bin/pint
echo "$files" | xargs git add

pre-push: run the tests that matter

A full suite on every commit is too slow to keep. Run it on push instead, where a failure is still cheap:

#!/bin/sh
php artisan test --stop-on-failure

commit-msg: keep the log readable

Reject empty subjects and very short ones. Everything stricter tends to get bypassed:

#!/bin/sh
subject=$(head -1 "$1")
if [ ${#subject} -lt 10 ]; then
  echo "Commit subject too short - say what changed and why." >&2
  exit 1
fi

Keep them honest

A hook the team bypasses with --no-verify every day is worse than none. Start with these three, keep them under a few seconds, and only add more when a real mistake slips through twice.

Code Review Habits That Keep Main Clean

Thu, 15 Oct 2026 00:00:00 GMT

Review works best when it is cheap.

Keep changes small

Small changes get read. Large ones get skimmed.

Say what and why

A short description of the change and the reason saves the reviewer a guess.

Review quickly

A review that waits a week blocks the next change too.

Shipping a Laravel App From Git

Thu, 15 Oct 2026 00:00:00 GMT

A Laravel deploy is mostly the same few steps each time.

Build from a known commit

Deploy a tag or a commit hash, not whatever is on a branch right now.

Run migrations deliberately

Run them as a step you can see, and know how to roll back.

Warm the caches

Config, route and view caches are part of the release, not an afterthought.

Why Teams Self-Host Their Git

Thu, 15 Oct 2026 00:00:00 GMT

Hosted Git is convenient. Self-hosting is about control.

Know where the code lives

Repositories sit on servers you run. You decide on backups, retention and who gets in.

Set your own access rules

Give people the access their role needs and remove it when they leave.

Keep it simple

Self-hosting only pays off if it stays easy to run. Pick tools you can update without a project.