3 minute read

⚠️ Replace repository names, branch names, workflow titles, etc., with your own.
Examples shown use my projects for demonstration purposes.

What This Guide Covers

This guide walks through a professional GitHub workflow using:

  • Git (CLI)
  • GitHub CLI (gh)
  • Feature branches
  • Pull Requests (PRs)
  • Merge strategies
  • Conflict resolution

This is structured for both:

  • 🔰 Developers learning clean branching workflows
  • 🧠 Builders who want disciplined, reproducible version control

1️⃣ Creating a Branch (essentially a sandbox)

A “sandbox” branch allows you to experiment safely without affecting main.

Example workflow:

Create audit/local-cleanup branch by running the following command

git switch -c audit/local-cleanup
  • This creates and switches to the newly created branch in one move.

Confirm the current branch

git branch --show-current

This displays the following

audit/local-cleanup

Use the following to display all available branches

git branch

Changes or experiments can now be performed in the newly created local-cleanup branch.

  • None of these changes will effect main branch until you merge changes.
    • We’ll cover opening a Pull Request (PR) and Merging changes further down below.

2️⃣ Adding & Committing Changes in local-cleanup Branch

While still in the branch

Perform these next crucial steps after making changes

  • add/stage changes
  • Best Practice:
    • categorized
    • small
    • incremental, and
    • reversible.
  • This keeps things tight, and CI/CD friendly

Run:

git add /path/to/file/where/changes/were/made
  • If noting changes, then all is well

Now we need to commit changes by running the following command

git commit -m "insert short commit message that explains what was done and why here"
  • You should notice a few lines providing commit log message.

Now we push changes to the remote repo

git push -u origin feat/local-cleanup

Safer alternative:

git push -u origin HEAD
  • You’ll notice some more log message during push.
  • Following this initial push you can simply run git push instead of using git push -u origin feat/local-cleanup

Some Branch Naming Convention Examples

  • feat/feature-name
  • fix/bug-description
  • docs/update-readme
  • chore/workflow-adjustment

3️⃣ Opening a Pull Request (CLI)

We’ll now walk through opening/creating a PR

Multi-line (PowerShell):

gh pr create `
  --repo DataEden/datainsidedata-website `
  --base main `
  --head chore/readme-badge-and-sanity-check `
  --title "Docs: dual-repo model + deploy sanity check" `
  --body "Adds README explanation + badge; adds a sanity-check step to deploy workflow."

Single line:

gh pr create --repo DataEden/datainsidedata-website --base main --head chore/readme-badge-and-sanity-check --title "Docs: dual-repo model + deploy sanity check" --body "Adds README explanation + badge; adds a sanity-check step to deploy workflow."

Reviewing PR Changes

Example:

gh pr diff 17
  • 17 represents the PR’s number.

You can also open in browser:

gh pr view 17 --web

4️⃣ Merging the Pull Request

After checks pass:

gh pr merge --merge --delete-branch

IF you still need the branch, run

gh pr merge --merge --delete-branch=false

5️⃣ Triggering a Workflow (If Needed)

gh workflow run "Deploy DID-LLC Jekyll site to GitHub Pages" --repo DataEden/datainsidedata-website

Verify runs:

Example:

gh run list --repo DataEden/datainsidedata-website --limit 3
gh run view --repo DataEden/datainsidedata-website --log

6️⃣ Updating Local Main

git checkout main
git pull --ff-only

Optional alias — This creates a custom Git command:

git config --global alias.pulldn "pull --ff-only"
  • Then you can simply type this simpler version instead of the longer git pull --ff-only

Example:

git pulldn

This is the method I employ.

  • It’s a shortcut that enforces clean, fast‑forward‑only pulls every time you use it.

7️⃣ Cleaning Up Branches

Delete local branch:

git branch -d branch_name

Delete remote branch:

git push origin --delete branch_name

Note: Branches should be deleted after merging to keep your repo clean. The only exceptions are branches that support ongoing or long‑term work, such as long‑running documentation updates, infrastructure changes, or experimental features you revisit over time.

8️⃣ Handling Merge Conflicts

Merge conflicts typically occur when:

  • Your branch is behind origin/main
    • changes on the remote aren’t reflected in your local branch.
  • Multiple branches modify the same lines
    • Git can’t automatically decide which version to keep.
  • Remote changes weren’t pulled before merging
    • Your local history diverged from the remote.

Clean Conflict Resolution Flow

gh pr checkout 17
git fetch origin
git merge origin/main

Resolve conflicts in your editor, then:

git add .
git commit -m "Resolve merge conflicts"
git push

🔐 Workflow Guardrails

Draft Phase

Add draft/ folder to .gitignore file so github doesn’t track your changes.

  • Rename freely
  • Experiment safely
  • No PR required

Publish Phase:

  • Create focused branches
    • Keep PRs small
    • Merge intentionally
    • Delete unneeded branches

Data Inside Data™.

Tech Hands, a Science Mind, and a Heart for Community™.

Updated: