GitHub Workflow with Git

Why a Workflow Matters

Git gives you the mechanics of version control, but a workflow defines how a team actually uses those mechanics. On GitHub, one common workflow is:

1. fork the repository if needed
2. clone it locally
3. create a feature branch
4. make and commit changes
5. push the branch
6. open a pull request
7. discuss code review feedback
8. squash and merge when approved

This structure helps teams collaborate safely without pushing unfinished changes directly to main.

Forking vs Cloning

A fork is your own server-side copy of someone else’s repository on GitHub. A clone is your local copy on your machine.

If you contribute to an open source project, you often fork first, then clone your fork:

git clone https://github.com/your-user/project.git
cd project

Then add the original repository as upstream:

git remote add upstream https://github.com/original-owner/project.git
git remote -v

This lets you fetch changes from the source project while pushing to your own fork.

Tip: In many company repositories, you may not need a fork because you already have direct branch access. The rest of the workflow still looks very similar.

Creating a Feature Branch

Start from an updated main branch:

git switch main
git fetch upstream
git pull upstream main

Create a branch for your work:

git switch -c feature/improve-git-docs

Feature branches keep your work isolated and make pull requests easier to review.

Making Changes and Committing Clearly

After editing files, inspect and commit your work:

git status
git add content/tutorials/git/git-basics.mdx
git commit -m "Improve Git basics examples"

If the feature takes multiple steps, create multiple logical commits rather than one giant commit.

Good Commit Practice in PRs

Useful commit messages make code review easier. Compare:

• bad: update stuff
• good: Add examples for git diff and git log

Pushing the Branch

Push your feature branch to your fork or shared remote:

git push -u origin feature/improve-git-docs

Now GitHub can display the branch and offer a button to open a pull request.

Opening a Pull Request

A pull request (PR) is a request to merge your branch into another branch, usually main.

A strong pull request usually includes:

• a clear title
• a brief summary of what changed
• context for reviewers
• test or validation notes
• screenshots if UI changes are involved

Example PR summary:

• Added beginner examples for git diff
• Clarified staging vs working directory
• Updated quiz wording

This saves reviewers time and reduces back-and-forth.

Code Review Best Practices

Code review is not only about catching bugs. It is also about clarity, maintainability, and shared understanding.

As the author:

• keep PRs reasonably small
• respond politely to comments
• explain trade-offs when needed
• update the branch if changes are requested

As the reviewer:

• focus on correctness and clarity
• be specific and constructive
• separate required changes from optional suggestions

Note: Good reviews improve team quality and knowledge sharing. They are not personal criticism.

Keeping Your Branch Updated

If main changes while your PR is open, you may need to update your branch.

One option is to rebase:

git fetch upstream
git rebase upstream/main
git push --force-with-lease

Another option is to merge main into your branch. Team preferences vary.

Squash and Merge

GitHub often offers Squash and merge, which combines all commits from the PR into one commit when merging.

Why teams like squash merging:

• keeps main history cleaner
• turns “work in progress” commits into one final logical change
• makes rollback easier for a single feature

A squash merge is especially helpful when a branch contains many small fixup commits.

Example Outcome

Your branch may have these commits:

Add Git basics examples
Fix typo in quiz
Adjust command formatting

After squash merge, main gets one clean commit such as:

Improve Git basics tutorial content

A Complete Example Workflow

git clone https://github.com/your-user/project.git
cd project
git remote add upstream https://github.com/original-owner/project.git
git switch main
git fetch upstream
git pull upstream main
git switch -c feature/add-git-stash-guide
# edit files
git add content/tutorials/git/git-stash.mdx
git commit -m "Add Git stash tutorial"
git push -u origin feature/add-git-stash-guide

Then open a pull request on GitHub, respond to review feedback, and squash merge when approved.

What You Should Remember

A GitHub workflow adds process around Git so teams can collaborate safely. Fork when needed, clone locally, work on feature branches, push to a remote, and open pull requests for review. Code review improves quality, and squash merge keeps history easier to read.

If you build one habit early, let it be this: never do meaningful team work directly on main.

Test Your Understanding

Exercise 1: Keeping your fork current

Scenario: You cloned your own fork of an open source project and want to stay updated with the original repository.

Question: Why did the tutorial have you add an upstream remote?

Exercise 2: Protecting main with feature branches

Question: In the workflow described, why should meaningful team work happen on a feature branch instead of directly on main?

Exercise 3: Understanding squash and merge

Scenario: A pull request contains three small commits: Add Git basics examples, Fix typo in quiz, and Adjust command formatting.

Question: What is the main effect of using GitHub's squash and merge option here?

---

Frequently Asked Questions

What is the difference between forking and cloning?

Cloning copies a repository to your machine; forking copies it to your own account on the hosting platform, and you then clone your fork. You clone when you have write access to the original. The normal case inside a company. You fork when you do not, which is how open-source contribution works: you push branches to your fork and open a pull request across repositories. In a fork workflow, origin is your fork and upstream is the original project.

How do I keep my branch up to date with main?

git fetch origin then either git rebase origin/main for a linear history or git merge origin/main to keep a merge commit. Rebase is the usual choice on your own feature branch before review, since it makes the pull request read as though written against current code. Remember it needs git push --force-with-lease afterwards, because the hashes change. Merge is the right choice if others are working on the same branch, as rebasing shared work strands them.

What is the difference between squash, merge and rebase merge on a pull request?

Squash merge collapses every commit in the branch into one on main. The tidiest history and the easiest to revert, at the cost of losing the individual commits. Merge commit keeps all commits and adds one joining them, preserving the full record and showing the branch in the graph. Rebase merge replays each commit onto main individually, giving a linear history that keeps them all but rewrites their hashes. Pick one, set it in repository settings, and stop thinking about it.

How big should a pull request be?

Small enough to review properly in one sitting. A few hundred changed lines is a reasonable ceiling. Review quality falls off sharply beyond that, and a large pull request tends to receive approval rather than scrutiny, which is the opposite of the point. If a change is genuinely large, split it: a mechanical refactor as one pull request, the behaviour change as another. Separating a rename or reformat from real logic changes is the single most effective thing you can do for reviewability.

Should I force-push to a pull request branch?

It is fine and often necessary, after a rebase onto main, or after squashing review fixes, provided you use git push --force-with-lease, which refuses if the remote has commits you have not fetched. What it costs is review continuity: a force-push can detach existing review comments from the lines they referred to. A common compromise is to add plain commits during review so reviewers can follow the changes, then squash on merge.

What should I actually look for when reviewing code?

Correctness first, then whether the change is understandable without the author present, then tests covering the behaviour rather than the implementation. Leave formatting to a linter. A review that spends its attention on spacing has spent it on the thing a tool should have handled. Be specific and direct about problems, ask rather than assert when you may have missed context, and distinguish blocking concerns from suggestions so the author knows what actually needs to change.