Github and Git Workflow

Contributing to open-source projects or collaborating on team projects is a valuable way to enhance your development skills and make an impact in the community. Whether you’re working on a project you own or contributing to a repository managed by someone else, having a clear and organized Git workflow is essential.

In this article, I’ll walk you through a full GitHub and Git workflow that covers everything from forking and cloning to branching, syncing, and making pull requests (PRs). This workflow is especially useful when contributing to projects you don’t own, but it’s also great for managing your personal repositories. Let’s dive into the process.

Forking, Cloning, Syncing, Branching: A Complete GitHub Workflow

1. Fork the Repository (GitHub)

The first step in contributing to a project that you don’t own is to fork the repository. Forking creates a copy of the repository under your GitHub account, giving you your own version to work with.

• Navigate to the repository on GitHub that you want to contribute to.
• Click the Fork button, usually located in the top-right corner.
• GitHub will create a copy of the repository under your account.

Now, you’ve forked the project and can start making your contributions independently.

2. Clone the Forked Repository to Your Local Machine

Once you’ve forked the repository, the next step is to clone it to your local machine so you can start working on it.

Open your terminal and run the following command, replacing your-username and repo-name with the correct values:

git clone https://github.com/your-username/repo-name.git

This command will download a local copy of the repository into a folder called repo-name on your machine.

Now, navigate into the project directory:

cd repo-name

3. Set Upstream Remote (Syncing with the Original Repo)

Over time, the original repository will get updated with new features, bug fixes, or other changes. To ensure that your fork stays up to date with the original repository, you need to set the upstream remote.

This command adds the original repository (referred to as upstream) as a remote:

git remote add upstream https://github.com/original-author/repo-name.git

To verify that everything is set up correctly, use:

git remote -v

You should see two remotes:

• origin points to your fork.
• upstream points to the original repository.

4. Create a New Branch for Your Work

It’s a good practice to create a new branch for each feature or bug fix you work on. This keeps your changes organized and isolated from the main codebase.

To create and switch to a new branch, use the following command:

git checkout -b feature-branch-name

This creates a new branch called feature-branch-name and switches you to that branch. Now, you’re ready to start making changes.

5. Make Changes and Commit

After working on the changes, it’s time to commit them to your new branch. First, check which files have been modified:

git status

Once you’re ready, stage the changes:

git add .

Then, commit the changes with a descriptive message:

git commit -m "Add description of what you changed"

6. Keep Your Branch Updated (Sync with Upstream)

Before you push your branch to GitHub, it’s essential to ensure that your branch is up to date with the latest changes from the original repository (the upstream). This prevents conflicts and makes sure your feature or bug fix is based on the most recent code.

Here’s how to sync your branch with upstream:

1. Fetch the latest changes from the upstream repository:

   git fetch upstream

1. Merge those changes into your branch:

   git merge upstream/main

Alternatively, you can use rebase if you prefer a cleaner history:

   git rebase upstream/main

7. Push Your Branch to Your Fork (GitHub)

Once your branch is up to date and you’ve committed your changes, it’s time to push your branch to your GitHub fork.

git push origin feature-branch-name

This pushes your local branch to your fork on GitHub, allowing you to open a pull request.

What is a Pull Request?

A Pull Request (PR) is a way to propose changes to a repository. It allows you to request that someone reviews and merges your code into the original repository. Pull requests are vital in collaborative projects, as they allow for a structured review process. Other developers can review your code, leave comments, suggest changes, or approve it for merging into the project’s main branch.

When you open a pull request, you compare the differences between your feature branch and the branch you want to merge into, often the main or master branch of the original project. This review and approval process ensures that changes are well-vetted and meet the project's requirements before being incorporated.

8. Open a Pull Request (GitHub)

Now that your changes are in your fork, it’s time to open a pull request (PR) to the original repository. Head over to your forked repository on GitHub, and you should see a prompt to open a pull request for the branch you just pushed.

• Click Compare & pull request.
• Write a descriptive title and summary of your changes.
• Ensure that the pull request is set to merge into the main branch of the original repository (upstream).

Once submitted, the repository maintainers will review your code and decide whether to merge it into the main project.

9. Address Feedback (If Needed)

It’s common for project maintainers to review your pull request and ask for changes or clarifications. If that happens, here’s what you need to do:

1. Make the requested changes in your local branch.
2. Commit the changes as usual.
3. Push the changes to the same feature branch:

   git push origin feature-branch-name

The pull request will automatically update with your latest changes.

10. Sync Your Fork’s main Branch with the Original Repository

As time passes, the original repository’s main branch will receive updates. To keep your fork in sync, follow these steps:

1. Fetch the changes from the original repository:

   git fetch upstream

1. Switch to your local main branch:

   git checkout main

1. Merge or rebase the changes from upstream/main:

   git merge upstream/main

Or, if you prefer:

   git rebase upstream/main

1. Push the updated main branch to your fork:

   git push origin main

This keeps your fork in sync with the latest changes from the original project.

11. Clean Up Old Branches

Once your pull request is merged or the feature is no longer needed, you can clean up the old branches to keep your repository tidy.

To delete the branch locally:

git branch -d feature-branch-name

To delete the branch on GitHub:

git push origin --delete feature-branch-name

Full Workflow Summary

Here’s a quick recap of the entire workflow:

1. Fork the repo on GitHub.
2. Clone your fork to your local machine.
3. Create a new branch for your changes.
4. Make changes and commit them.
5. Fetch and merge changes from the original repo (upstream).
6. Push your branch to your fork.
7. Open a pull request to the original repository.
8. Update the pull request based on feedback.
9. Sync your fork’s main branch with the original repo.
10. Clean up old branches once they are merged or no longer needed.

By following this organized GitHub and Git workflow, you can efficiently contribute to open-source projects or manage personal repositories while keeping your codebase clean and in sync with the original project. Happy coding!