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

Let's see how well you understood the concepts! These exercises will help reinforce what you just learned.

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?