Git & GitHub 101

• Definitions
  • What Is Git?
  • What Is GitHub?
• Basic Workflows to Contribute to the Open Source Using Git and GitHub
  • Forking a Repository
  • Authenticating with GitHub
  • Cloning a Repository
  • Adding an upstream Remote Repository
  • Check the Added Remote Repositories
  • Create a New Branch
  • Add and Commit Changes
  • Fetching upstream Changes
  • Synchronizing Changes Locally
  • Resolve Merge Conflicts
  • Push Changes
  • Making a Pull Request
• Advanced Git and GitHub Workflows
  • Asynchronous Collaboration on a Shared Branch Between Two Different Forks
  • Synchronous Collaboration
• Getting the Most Out of Your GitHub Profile
  • How Does It Work?
• Resources to Learn Git and GitHub

We like this Git definition from Amazon Web Services:

Git is a distributed, open-source version control system (VCS) that enables you to store code, track revision history, merge code changes, and revert to earlier code version when needed.

Like GitLab and Bitbucket, GitHub is a platform for hosting, sharing, and collaborating on Git repositories.
You can interact with GitHub through the web GUI on their website, and there is also a GitHub CLI if you prefer working with the command line.

Back to Top

Suppose you want to contribute to an open source project. In that case, the first step is to fork the repository to your GitHub account. Most open sources do not allow you to make and push changes directly in their repository. That's why you want to fork the repository.

Forking means you create a copy of the repository in your GitHub account to make changes without pushing commits directly to the project's original repository.

The steps to do so are:

1. Click the "Fork" button on the project's repository page on GitHub.
2. GitHub will redirect you to the "Create a new fork" page. Click the "Create fork" button.

By convention, this forked repository is called the origin repository.

Suppose you work for the first time with GitHub locally. In that case, you want to know about authenticating your local Git with GitHub before cloning a repository.

You must provide your email and credential whenever you clone a repository, commit and push changes, or do other Git activities related to GitHub locally. That is a way for GitHub to authenticate you as a user. But you can set up your credentials locally, so you don't have to input them whenever you do a Git activity.

There are three ways to clone a repository:

• HTTPS
  HTTPS is the most common one to use. You must create a Personal Access Token to enter when GitHub prompts your password.

• SSH (Secure Shell)
  SSH provides an encrypted way to exchange information safely. You can read here to generate a new SSH key on GitHub.

• GitHub CLI
  You can copy and run the command in your terminal using GitHub CLI.

When you want to start working on a change, you want to clone the project's repository after you fork it. That way, you can work on it in the local environment.

The steps to clone a repository:

1. Go to your forked repository on GitHub.

2. Click the green "Code" button.

3. Choose how you want to clone it—through HTTPS, SSH, or GitHub CLI.
   For this example, we will use HTTPS.

4. Copy the URL.

5. In your terminal, run:

   git clone repo-url
   

   Change the repo-url to the copied URL of the forked repository.
   Running this command will set up a copy of the repository on your local computer for you to work with.

Even though you've cloned the forked repository, you may also want to add the original repository as one of your remote repositories. This original repository is conventionally called upstream. By doing this, you can pull other people's changes into your local repository whenever you need.

To add an upstream repository, run this command:

git remote add upstream repo-url

Change the repo-url with the URL of the original repository.

Now you have the origin and upstream as your remote repositories. You can check if they've been appropriately added by running this command:

git remote -v

Running this command will give you a list of your remote repositories.

Now you're ready to work on the changes. Always work on changes in a new branch, not directly in the main or master branch. This new branch is what you will later push to the remote repository.

To create a new branch, run this command in your terminal:

git checkout -b new-branch-name

Change new-branch-name to whatever you want.

Say that you've finished making changes and are ready to push your changes to GitHub. You first need to add and commit your changes.

Add Changes

Run git add . to add all new and modified files to the Git staging area.

Or run git add path if you want to add a specific directory or file.
Change path to the path of the file that you want to add. For example:

git add styles/header.css

Commit Changes

Now you can 'save' your changes by committing with this command:

git commit -m "Your message"

Change Your message into a short description of your changes. For example:

git commit -m "Add navbar to the homepage"

Run git status

You can check if your changes have been added or committed by running the git status command in your terminal. This command will let you know the state of your Git working directory and staging area.

Sometimes, someone works in the same file as you. And maybe, that person already pushed their changes and got their pull request merged into the main branch on the upstream repository while you are working on yours locally. So you always want to ensure that your fork is up to date with the upstream repository.

1. Go to your forked repository on GitHub.
2. Click the "Sync fork" button under the green "Code" button.
3. If the buttons are inactive, the repository has no changes. You can push your changes and make a pull request in that case.
   But when the button is green with "Update branch" stated, you want to click it.

Now your fork has the same update as the upstream repository.

Now that your origin repository is in sync with the upstream, you want to synchronize these changes locally. That way, you already have the most updated content when you push your changes.

You want to fetch and merge the latest update into your working branch. In your terminal, make sure that you're in your working branch. Then run:

git pull origin main

Change main to master if the repository uses master as the name of its default branch.
The command fetches the updated main branch from the origin repo and merges that branch into your local working branch.

In this step, you should resolve some merge conflicts, if any.

It's common to encounter merge conflicts when contributing to open source. Conflicts usually occur when changes are on the same line(s), in the same file(s), from 2 different branches.

Say you forget or haven't fetched the upstream and synchronized it with the origin and local repositories before pushing your changes. When you're about to create a pull request on GitHub, you will get notified about the conflicts, if any.

There are two ways to resolve conflicts:

1. Directly on GitHub

   You will get a notification prompt that your branch has conflicts that must be resolved.
   Click on the "Resolve conflict" button to fix the conflicts.

   

   However, the best way is to resolve them in your local environment.

2. In the local environment

   • Do all the steps in Fetching upstream Changes and Synchronizing Changes Locally sections.
     Then you will see this in your text editor:

     

     
     

   • Select one of the options:

     • Accept Current Change—when you only want to keep your change.
     • Accept Incoming Change—when you only want to keep the incoming change.
     • Accept Both Changes—when you want to keep both your and the incoming changes.

After resolving the conflicts, if necessary, you can fix and adjust the codes. Then add and commit the changes.

Credit: How To Use GitHub For Project Collaboration — Based on Agile Method by Ayu Adiati

You have fetched and synchronized updates and also added and committed the changes. Now you can push your changes to the remote repository. Remember that you will push these changes to the origin repository.

To do so, run this command in your terminal:

git push origin branch-name

Change the branch-name to your working branch name.

Once you have pushed your changes to the origin repository, you can submit the changes to the upstream repository by making a pull request.

Creating a pull request allows the maintainers to review your work, comment, and request any necessary changes. They will then decide whether to merge or not merge your changes into the project codebase.

The steps to make a pull request:

1. Go to the upstream repository at GitHub and click the green "New pull request" button. If you have recently pushed changes to GitHub, you should see a banner at the top of the page with a "Compare and pull request" button that you can click on.
2. You will then get taken to the "Open pull request" form, where you can create a description of your pull request. Many projects provide a pull request template within the form to help you get it right. But if they don't, you should check the project's Contributing guidelines (usually written in the CONTRIBUTIONS/CONTRIBUTING markdown file) and follow any conventions described.
3. Once ready, click the "Create pull request" button.

Congratulations! You have made your pull request 🎉!

If a maintainer requests changes, you can make the requested changes and push new commits to the same branch. They will automatically be added to the pull request.

Back to Top

Let's assume you and your teammate, Alice, forked a project repository. You will collaborate on the same issue in the same file asynchronously. Each of you will do the same steps.

In this example, we will walk you through your point of view.

Add a Remote Repository

Add Alice's fork as a remote on your local repository by running this command in your terminal:

git remote add alice repo-url

Change repo-url to the URL of Alice's fork.

We use alice as the name of the remote repository as an example because we add Alice's fork as one of our remote repositories. But you can name this anything you want.

Fetch Branches

Fetch Alice's branches by running this command:

git fetch alice

Go to the Target Branch

git checkout branch-name

Change branch-name to the target branch name at Alice's fork.

Pull the Changes

Pull the changes pushed by Alice with this command:

git pull alice branch-name

Now you have the updated branch version with the changes from your teammate.

You or Alice can submit the pull request once you have done all the work. Each commit will automatically contain either your or Alice's name. So, both of your contributions are identified.

Say sometimes you work synchronously with Alice and Charlie on the same issue. All steps are the same as the asynchronous collaboration above. But in sync collaboration, you want to include them in your commit message as co-authors.

git commit -m  "Add new feature
>
>
Co-authored-by: Alice <alice@email.com>
Co-authored-by: Charlie <charlie@email.com>"

Notes:

• Because you are the one who commits the changes, you don't need to include your name in the commit message.
• Always give two empty spaces by hitting enter before writing "Co-authored-by".
• Do not close the commit message with double quotes (") before you add the "Co-authored-by:".
• Close the commit message with double quotes (") at the last line of "Co-authored-by:".
• Use the email address associated with your teammate's GitHub account.

Back to Top

Do you know that you can customize your GitHub profile? You can add a short bio, website, and social media links and customize your pinned repositories to showcase the work you most want the world to see. It would be like a mini portfolio of your own!

To customize your profile, create a repository in your account with the same name as your GitHub username and pop in a README. The contents of that README file will get rendered on your profile page. You can add all kinds of cool integrations to this README to do awesome things on your profile.

These articles can give you some inspiration:

• Mini Portfolio: Bring Your GitHub Profile To The Next Level by Ayu Adiati
• Creating a Killer GitHub Profile README by Braydon Coyer
• How to create beautiful Github profile README.md by Indrajeet Nikam

Back to Top

• GitHub Docs
• GitHub Skills

If you have recommended resources to be added to this section, drop them in our discussion board! We'd love to hear from you!

Back to Top