Updated 2023-01-30

GitHub Cloning Repo

Overview

  • In order to make any useful changes to a GitHub repo, collaboraters need to have their own copies of it, make their edits, and push the changes to the GitHub repo. This part of the tutorial will go over the first and one of the most fundamental step of this process which is storing your own copy of the repo.
  • Cloning refers to the act of copying the GitHub repo stored remotely to your local machine.

Step 1: Obtaining Remote Repo URL

Before copying a remote repo to your local machine, you need to know what and where the repo is. * First make sure to have read permission from the GitHub repo. * Open up the GitHub repo on any web browser, click on the green button that has the down arrow and the word Code, and copy the URL there. The url from either HTTPS or SSH should be fine. * Screenshot

Step 2: Copying to Local Machine

This step assumes the user now has the URL of the GitHub repo the user wishes to clone. It's now time to use this URL of the remote repo to copy to user's local machine. * Navigate to the working directory you wish to clone the repo using cd command. * Enter git clone followed by the URL of the repo that was copied from previous step. The following example copied the SSH URL but HTTPS should be fine as well. git clone git@github.gatech.edu:<owner>/<repo name>.git * Wait until the repo is done cloning

Cloning into `<repo name>`...
remote: Enumerating objects: 43, done.
remote: Total 43 (delta 0), reused 0 (delta 0), pack-reused 43
Receiving objects: 100% (43/43), 1.26 MiB | 9.61 MiB/s, done.
Resolving deltas: 100% (10/10), done.
  • Enter ls and the repo should be successfully listed and stored locally in user's machine.

GitHub Forking Repo

Overview

  • A central GitHub repo can often have many collaborators depending on the many files stored there.
  • Pushing broken code or files to the repo can be disastrous and it would be useful to have a seperate experimental version of the repo on GitHub. This is where the concept of forking comes in.
  • As opposed to cloning, forking a repo allows user to:
  • (1): create their own copy of the repo stored on GitHub to freely experiment
  • (2): edit the central repo through use of a pull request which waits on approval of the owner
  • Important Terminology:
  • Upstream: central repository (central repo and upstream will be used interchangeably)
  • Downstream: local copy/information on user's end
  • Pull Request: notification of the edits user made downstream and request to merge them on upstream repo

Step 1: Fork the Repo ##

This section will go over how to fork a repo from upstream. Please note that a forked repo is not completely private to the user as any collaboraters given access to the upstream repo can also have access to the user's forked version. * First make sure to have read permission from the central repo. * Open up the central repo on any web browser. * On the top right corner of the page, click on where it says Fork and then click on the user. * Screenshot * Once this process is finished, there should be the forked repo in the format of <user ID>/<repo name>. * Clone the forked repo.

Step 2: Setting Up Remote and Pull Request

At this point, the user should have forked the repo and be able to freely edit it normally. If user runs git remote -v command in the repo, the origin should already be set to the forked version like this:

origin  git@github.gatech.edu:<user>/<repo name>.git (fetch)
origin  git@github.gatech.edu:<user>/<repo name>.git (push)

The example above is in the SSH format but HTTPS will also be fine. This step will walk through setting up remote with central repo and how to make pull requests. * Open up the central repo on any web browser, click on the green button that has down arrow and the word Code, and copy the URL there. * Screenshot * cd into the forked repo on local machine. * Type git remote add upstream <Central repo URL>. If the user now types git remote -v, origin should point to user's forked repo and upstream should point to the central repo like this:

origin  git@github.gatech.edu:<user>/<repo name>.git (fetch)
origin  git@github.gatech.edu:<user>/<repo name>.git (push)
upstream git@github.gatech.edu:<organization name>/<repo name>.git (fetch)
upstream git@github.gatech.edu:<organization name>/<repo name>.git (push)
  • To send a pull request which will send edits from forked repo upstream:
  • push any edits to the forked repo first.
  • open up the forked repo on any web browser and click on Pull request which should be below the green Code button as shown in the previous screenshot.
  • There should be a green check mark with the notification Able to merge. If not, this can either mean the corresponding repo and branches for the pull request don't match or there is a merge conflict issue. More details on merge conflicts and how to resolve them can be found here. Screenshot
  • Click on the green button that says Create pull request. The pull request is sent upstream and once the owner of central repo approves it, the edits made downstream should be present in the central repo.

Optional Step: Update Repo Downstream

To avoid the chances of a merge conflict occurring or to update the forked repo with changes made on central repo, the user must update the forked repo downstream. This is equivalent to the git pull command done normally on git:

git fetch upstream
git merge upstream/<branch>