How to use GitHub October 14, 2018

Table of contents

• 1. Install Git
  • 1.1 Windows
• 2. Create a GitHub account
  • 2.1 Join an organization
• 3. Setup your SSH key
• 4. Clone the project
  • 4.1 Fork the project
  • 4.2 Add a remote
• 5. Create a new branch
• 6. Commit often
  • 6.1 Rebase often
• 7. Push
• 8. Create a pull request

So you want to use GitHub? Or maybe you have to, because it's your company's main repository. In any case, in this article I'll go in details on how to do just that, from the very beginning all the way to your first code contribution.

1. Install Git

First things first, if you want to use Git, you'll need it on your workstation. Head over to Git's download page and download the installer. Once the installer has finished downloading, simply run it and follow the instructions.

1.1 Windows

As Git is mainly a command-line tool, its installation can feel trickier on Windows. Luckily for Windows users, Git provides a neat installer to do all the work. Still, there are quite a few choices to make during the process and they came seems daunting at first. Let me walk you through the steps of the installer.

• Select components screen
  • Recommended
    • Git LFS (Large File Support)
    • Associate .git configuration files with the default text editor
    • Associate .sh files to be run with the Bash
  • Optional
    • Windows Explorer integration: Useful if you don't like to navigate via the command line (using cd commands), this will add two options in the right-click menu of a folder to open the Git console and GUI.

• Choosing the default editor used by Git screen
  • Notepad++: If you don't have it already, you can download it from their download page.

• Adjusting your PATH environment screen
  • Use Git from Git Bash only: This is the recommended option and should be the one you choose. Consider the other options only if you really require them. If you're unsure, you don't require them.

• Choosing HTTPS transport backend screen
  • Use the OpenSSL library: unless your organization requires you to use the Windows Secure Channel library, the default is recommended.
• Configuring the line ending conversions, screen
  • Checkout Windows-style, commit Unix-style line endings: This is the option that will give you the least amount of trouble, so I recommend it. Unless you configure your code editor to properly manage Unix-style line endings, having Windows-style line endings will make your life easier. Whatever you do, do not choose Checkout as-is commit as-is, especially if you have team members working on Unix systems (lots of open source contributors use Unix systems).
• Configuring the terminal emulator to use with Git Bash screen
  • Use MinTTY: The default works perfectly fine. Compared to Windows bash, it handles non-Unicode characters better and has colours (who doesn't like colours?).
• Configuring extra options screen
  • Recommended
    • Enable file system caching
    • Enable Git Credential Manager
  • Optional
    • Enable symbolic links: If you're on Windows, chances are you're not using these very much. Not required.

2. Create a GitHub account

Now that you have Git installed on your local computer, it's time to create a GitHub account! Fill the sign-up form on their website. You may need to validate your email address to finish the registration process.

2.1 Join an organization

Organizations are groups of users (people) along with the repositories (projects) they contribute to. They are a common and convenient way to manage permissions and roles in a consistent manner across multiple projects. For example, if you look at the CakePHP organization, you will see that a team of about 40 contributors works on upwards of 60 repositories. They use the organization as a way to white-list people that have write permission on the important branches of their projects, such as the main development branch, the current release branch, etc.

If you want to contribute to projects inside an organization, make sure to request access to their administrator. This may not apply to you for now, but it might sooner than you think!

3. Setup your SSH key

You're signed-up, your email address has been validated and you're ready to code! Well, almost. There are two ways to work with Git: using HTTPS and using SSH. HTTPS is very convenient in that is doesn't require any additional setup and you could start working right away. The downside is that in order to authenticate you, GitHub will ask you for your credentials (username and password) again and again and again... To avoid this, I therefore recommend using SSH. To do so, you will need to generate a special signature unique to your workstation, your SSH key, and give it to GitHub so it knows it's you. Git will then automatically provide this key to GitHub every time you would need to authenticate, all on its own.

Follow the steps of the GitHub's SSH key setup guide and come back here when you're all done.

4. Clone the project

Alright, ready? Let's copy the source code of the project on your workstation! Actually, we'll do more than that: we will copy the entire repository, which consists of the source code AND all of its previous revisions, on your workstation! This is because, as opposed to other versioning system such as SVN, Git is completely decentralized. Every copy of the repository IS the full repository, meaning that even if the "master" copy on GitHub disappears, nothing is lost. To clone a project, follow these steps:

1. Navigate to the project you want to clone in GitHub
2. Click the green "Clone or download" button

• Make sure the pop-up says "Clone with SSH". If it doesn't click the "Use SSH" link at the top-right of the pop-up

3. Copy the string provided. It should start with git@
4. Open your Git command-line or terminal
5. Using cd commands, navigate to where you want to project's folder to be cloned to
   • Example: if you want the project to be in C:\workspace\java\<project>, navigate to C:\workspace\java
6. Type git clone followed by the string you copied from GitHub and press Enter
   • If this is the first project you clone from GitHub, you will receive a warning about the fact that the authenticity of the host cannot be established. Verify that the host is in fact GitHub, and then press y, e, s, Enter

Git will then clone the repository to a folder with the same name as the project. The complete console log should look like this:

$ git clone git@github.com:<organization>/<project>.git
Cloning into '<project>'...
The authenticity of host 'github.com (192.30.253.113)' can't be established.
RSA key fingerprint is SHA256:<some long random-looking string>.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'github.com,192.30.253.113' (RSA) to the list of known hosts.
remote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 1366 (delta 0), reused 0 (delta 0), pack-reused 1365
Receiving objects: 100% (1366/1366), 18.71 MiB | 5.79 MiB/s, done.
Resolving deltas: 100% (975/975), done.
Checking connectivity... done.
$ cd <project>

4.1 Fork the project

If you work on someone else's project, it is usually preferable to fork it before cloning it. Forking a project will simply copy the repository under your own namespace. It's a good idea to do so because it gives you your own copy of the project with which you can do as you please. It also has the benefit of restraining any screw-ups that might happen in your own copy, without any consequence to the main one.

To fork a project, simply navigate to the project's page on GitHub and click the "Fork" button (near the top-right), then select the namespace you want to fork it into (normally, your username's).

Once you've forked the project, you can clone it as detailed in step 4 above. Then, proceed to step 4.2: Add a remote.

4.2 Add a remote

A remote is a link between your local version of the repository and a fork that isn't your own. For example, if you forked the main repository into your own namespace and then cloned that fork, you should add the main repository as a remote to be able to stay up-to-date with the changes happening there. To add a remote to your local repository, run the following command:

$ git remote add --track <main branch on remote> <local name of remote> git@github.com:<organization>/<project>.git

Where:

• <main branch on remote> is the name of the branch you wish to track locally. Must exist in the parent repository.
• <local name of remote> is the name you are going to give to the parent repository on your workstation. It's entirely up to you. I like to use upstream for the main remote.
• git@github.com:<organization>/<project>.git is the string you would use to clone the parent repository (from the green "Clone or download" button)

*For more information, see Git's documentation on remotes.

Example:

$ git remote add --track master upstream git@github.com:<organization>/<project>.git
$ git remote
origin
upstream

5. Create a new branch

Working in a branch separate from the main one helps keeping things clean and organized. It also helps to easily be able to go back to a stable version of the code. When using feature-branches with Git, a new branch should be created for every single change you wish to make, no matter how small. To create a new branch, follow these steps:

1. Make sure your local repository is up-to-date
   • If you work directly on the main repository, simply run:
     • git fetch --all to get any new changes from the main repository you might not have locally
     • git checkout origin/master to jump to the latest stable commit
   • If you work in your own fork, run:
     • git fetch --all to get any new changes from the main repository you might not have locally
     • git checkout master to go to your main local branch
     • git rebase upstream/master to apply the changes from the main repository to your local one
2. Create a new branch using the git checkout -b <new branch name> command
3. Code!

6. Commit often

Committing changes into Git is akin to pressing the "Save" button in a text editor: you should do it all the time. It's almost impossible to lose work once it's been committed into Git. So, since you don't want to lose work, commit often! Don't worry about messy commits: you can always amend the last commit to fix it later or even squash multiple commits together to tidy it up. Don't let that hinder you from committing often. To commit changes into Git, simply follow these instructions:

1. Open your Git command-line or terminal
2. Using cd commands, navigate to your project's folder
3. Run the git gui command
4. Click the "Rescan" button to allow the UI to pick-up your latest changes
5. Stage the changes you want to commit from the top-left pane to the bottom-left pane by selecting them and pressing Ctrl+t
   • You can Ctrl+click or Shift+click the files
6. Write a clear and concise commit message on the first line, leaving the details to the next lines if required
7. Press the "Commit" button

6.1 Rebase often

If you work on a project as a member of a team, changes will constantly be merged into the main repository while you're working on yours. If you wait too long before syncing your local repository with the changes from the main repository, the code you're working on might end-up needing some serious adjustments or could even not be required anymore! To keep up with the changes, I recommend rebasing at least daily, depending on the size of your team and the frequency at which changes are merged into the main repository. To rebase, run:

1. git fetch --all
2. git rebase upstream/master
3. Fix the resulting conflicts, if any

7. Push

Once your changes are ready, you can send them to GitHub using the push command. This will update the repository on GitHub with the changes that are currently only in your local repository. To push, simply run the git push command. If this is the first time you're pushing the branch, Git will let you know that you have to add some flags to the command. Copy the command given by Git and push your changes. The complete console log should look like this:

$ git push
fatal: The current branch <branch name> has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin <branch name>

$ git push --set-upstream origin <branch name>
Total 0 (delta 0), reused 0 (delta 0)
To git@github.com:<organization>/<project>.git
 * [new branch]      <branch name> -> <branch name>
Branch <branch name> set up to track remote branch <branch name> from origin.

8. Create a pull request

You've done it: you've created a new change set in a branch! Ready to request to the repository administrator to take your contribution? Alright, first of all, head to GitHub and navigate your way to the main repository's page. Next, you will see a new yellow alert that wasn't there before. It will look like this:

Click the "Compare & pull request" button. This will bring you the pull request submission form. That form is divided into different parts:

Let's take a look at them. At the top is the title of your pull request. Keep in mind the tips shared above about the first line of the commit message: the pull request title should respect those too. Once that's filled out, it's a good idea to describe what you did, at a high level, into the comment field. Add any important details you can think of and also any links to issues or tickets fixed or impacted by your pull request. Having cross-references make it much easier to go back and track the reason why certain changes happened.

Then there's the right sidebar. Its first section is to request reviews. I recommend all pull requests to be reviewed. By whom? Well that depends, but a good rule of thumb should be to assign pull requests to people that are intimately familiar with the area of the code you changed. They are the ones that will be able to make the most insightful comments about your changes. Those experts will also be able to tell you if you broke some fundamental assumption of the code that you might not have known about. In any case, always having at least one review never hurts. The second section is about the assignee. That person is the one that is responsible to formally accept your pull request into the repository. When you've filled everything, finish by clicking the green "Create pull request" button.

There you go, you got through it all! Through this tutorial we've seen how to get the code base of a project from GitHub to your computer, how to stay up-to-date with the other contributors and finally, how to push your changes back to the master repository. Feel free to come back this page if need be: the commands never change and having a reference sheet is always handy. There is much more to learn about Git and GitHub but for now: go on and contribute!

— Etienne Lamoureux