Creating an Account

You don’t need an account on GitHub to access public repositories. If you want to upload code, or participate in conversations about the code, you will need to create an account. It is, fortunately, very straightforward to set up an account; and for public repositories, it is free. A free account is sufficient for everything covered in this chapter.

Step 1: Create your account

1. Navigate to https://github.com (Figure 10-1).

2. Enter a unique username. GitHub will let you know if the name has already been selected.

3. Enter a valid email address.

4. Enter a secure password.

5. Click the button Sign up for GitHub to proceed.

After passing the validation tests for a unique username, a valid email, and a secure password, you will be directed to the next screen.

Step 2: Select a plan

At this point, you may choose to financially support GitHub by paying for a plan. There is absolutely no requirement to pay for this code hosting service. By default, GitHub chooses the free plan for you (Figure 10-2). You’ll need to follow these steps:

1. Confirm the plan type you would like to enable. By default, the free plan is selected.

2. Complete the account creation process by clicking Finish sign up.

Figure 10-1. Sign up for a GitHub account

After you have created your account, you will receive an email from GitHub asking you to confirm your email. You will need to click the link in this email to complete the account creation process. If you do not verify your email, you will not be able to complete some tasks.

You are now ready to use your account to perform a range of tasks, including creating new repositories, and contributing code to your own and other repositories.

SSH Keys

If you use a very secure password, you may be using a password generator and have a password that is 45 characters including letters, numbers, and special characters. No one wants to retype this kind of password, but in order to authorize uploads, you will be prompted for your password when you try to push code up to GitHub. By uploading your SSH key, you can avoid retyping your password each time you want to publish code.

Figure 10-2. Select a plan for your GitHub account

Appendix D includes instructions on how to create and retrieve SSH keys. Once you have the public key copied to your clipboard, you are ready to proceed to GitHub:

1. Navigate to https://github.com/settings/ssh. You can also access this screen by logging in to your account, clicking the configuration cog (top right), and then clicking SSH Keys from the set of navigation options for your account.

2. On the SSH Keys summary screen, click Add SSH key.

3. Optionally, add a title for your SSH keys. For example, you might have a personal set of SSH keys, rather than the keys you generated for your work computer.

4. Paste the public key that you copied previously into the Key field.

5. Click the button Add key.

SSH Keys Must Be Unique

GitHub will only allow key pairs to be added once on its system. If you have already use these keys on a different account, you will get an error message when you try to save the keys.

You will now be able to perform actions from your local computer that require authentication without typing your GitHub password.

Creating an Organization

Assuming you will be working on an open source project, you may want to create an organization at this point as well. An organization is able to own projects. Multiple people are able to join (or be assigned to) an organization. This allows you to manage a project without having to create a second GitHub account. Organizations are free to create, so you may as well take advantage of them.

To create an organization, complete the following steps:

1. From the top menu, click the + symbol next to your avatar.

2. Click New organization. You will be redirected to the setup form for new organizations.

3. On the form Create an organization, enter the following:

   • Organization Name: This will be the URL for your organization.

   • Billing email: This is a required field even if you are selecting the free plan.

   • Plan: Open source is selected by default.

4. Click Create organization to proceed.

On the next screen you can add team members to your organization. Your own account is added by default. To add additional accounts, complete the following steps:

1. In the search field, enter the name or username of the person you want to add.

2. To the right of the person’s name, click the + symbol.

3. Repeat steps 1 and 2 for each person you would like to add.

4. Click Finish to send the invitations.

Your organization has been created, and it has been assigned new members as you designated while setting up the organization.

Personal Repositories

This section is a brief overview of putting your own repositories on GitHub. You will use your personal account to create a new repository, which is appropriate for projects you do not intend to have others contributing to on a regular basis, because they are essentially yours. For example, when I deliver conference presentations with HTML slides, I often publish them to a GitHub repository to share them.

Creating a project

A repository on Git is so much more than what you get locally on your computer when you run the command init in a directory. It has an issue tracker, the ability to convert Markdown files into web pages, supplemental wiki pages, charts, graphs, and more. GitHub, however, still refers to the process as creating a repository.

To begin the process of creating a new repository, locate and click the + icon in the top-right corner of the screen, and then select New repository (Figure 10-3).

Figure 10-3. Create a new repository

Alternatively, you can log in and then navigate to the home page of GitHub; then locate and click the button Create new repository.

Once you’ve initialized the process, you will be redirected to a screen where you are asked to fill out the details for this project (Figure 10-4). The information you will need is also summarized in Table 10-1.

Figure 10-4. Enter the details for your new repository

Table 10-1. Details needed to create a new GitHub repository

Field	Notes	Use if importing?
Repository name	Your new project will be available at the URL https://github.com/<username>/<repo-name>. Choose something short, but descriptive.	Yes
Repository description	This text will appear at the top of the repository home page, above the list of files.	Yes
Visibility	Choose public (selected by default) or private (requires a paid account).	Yes
Initialize this repository with a README	Add an empty file that can be used for details about your project. This file will be rendered as HTML on the home page for your repository, but can be written in Markdown.	No
Add .gitignore	Many programming languages will generate compiled files during the build process that should not be included in the repository. You can generate a .gitignore file now, which has typical file extensions for your language already included.	No
Add license	Without a license file, you do not give people permission to download and use your code. You retain full copyright, and do not grant permission for others to use your work. Ideally, your project will have a license. If you would like to include a license, but aren’t sure which one to choose, Choose a License may help.	Maybe

If you have already started a repository locally, you may choose to upload it to this new project; however, if you have created files during the initialization process, you will need to first download these changes, incorporate them into your local repository, and then push them back up to GitHub. To avoid this extra step, if I already have a repository locally, I will omit the creation of the files for README, .gitignore, and the license.

Once you have selected values for each of the items in Table 10-1, locate and click the button Create repository. Your new repository will be created, and you will be redirected to a summary page with suggestions on what to do next (Figure 10-5).

Figure 10-5. Your new repository is ready for use

Because there were not any files initialized during the repository creation process, you have only two options at this point: upload a repository from your local computer, or import a project from a publicly available URL. If, for example, you wanted to copy your GitLab project from earlier in the book, you could. These options will be covered next.

Importing a repository

If you have been following along from the beginning of this book, you will have created a repository on GitLab that was a clone of the workshop files for the Git for Teams workshop. You can easily import this repository into GitHub. This process can only be completed if there are no files in your GitHub repository:

1. Navigate to your project home page.

2. If the repository is empty, you will be able to locate and click the button Import code. Clicking on this button will redirect you to the GitHub importer.

3. Enter the URL for the repository you want to import. This must be a public project, but it does not need to be a Git repository. You can also import Subversion and Mercurial repositories. If you are importing a Git project, ensure you get the full URL, including the .git extension—this is the same URL structure that you would use to clone a repository locally. Figure 10-6 shows a valid URL for a project (https://gitlab.com/gitforteams/gitforteams.git).

Figure 10-6. Enter a valid URL for a Git repository to import it to GitHub

4. Click Begin import. The import process will begin.

5. When the import process has completed, click Continue to repository. Your files will have been imported from the remote repository (Figure 10-7).

Figure 10-7. The repository files and history have been successfully imported from GitLab into GitHub

$ git remote add origin https://github.com/gitforteams/glowing-octo-dangerzone.git

$ git push --set-upstream origin master

Making Commits via the Web

One of the nice things about using a code hosting system such as GitHub, and not just working at the command line, are the tiny enhancements that are built into the system. For example, GitHub allows you to edit any of the files in your repository through a web user interface. While I recommend you do not use this as your regular code editor, it can be really handy if you just want to fix a typo as a fly-by commit.

To make an edit via the web editor, complete the following steps:

1. Navigate to the specific instance of the file you want to edit. The URL for this file will include the branch name. For example, https://github.com/gitforteams/freezing-batman/blob/master/README.md.

2. Locate and click the pencil icon to edit this file (Figure 10-8); alternatively, press e on your keyboard.

You will be redirected to a browser-based text editor (Figure 10-9). You are now ready to make changes to the file in your repository.

After making edits you can click the button Preview changes. New lines have a green bar to the left of the changed text (wrapped in the HTML element ins); lines that have been removed have a red bar to the left (wrapped in the HTML element is del). In Figure 10-10, the first paragraph with a bar has been removed; the second paragraph is new. Apart from color and the HTML elements, there does not currently appear to be a way to perceive the difference in what’s been added or removed.

Figure 10-8. You can edit any text file by clicking the pencil icon

Figure 10-9. The browser-based text editor includes an optional preview

Once the edits have been made to the file, you are ready to commit your changes back to your repository (Figure 10-11). A default value is provided for a short commit message, which states which file is being updated. You should provide a more descriptive description of the edits being made. An optional extended message can also be added. You will need to decide if you want to just commit the changes to the current branch, or if you want to create a new pull request from this change. By default, GitHub assumes you would like to commit this change directly to the repository, and on the same branch.

Because you are working with your own project at this point, it’s fine to commit the change back to the master branch; leave the default option selected and click the button Commit changes.

Figure 10-10. The preview shows which lines have been changed (the first line has been removed; the second has been added)

Figure 10-11. Committing your changes back to the repository

Why You Might Want to Submit Yourself a Pull Request

If you are the sole editor for your project, you probably don’t need to create a pull request for your changes. Pull requests, however, are merged back into the master branch with the parameter --no-ff. This means it will show up in your graphed history as a blip outside of the straight line of the master branch. If you don’t mind if this commit appears exclusively on the main branch, it’s fine to omit the pull request step. The step-by-step instructions for creating and closing pull requests are covered later in this chapter.

Once you’ve committed your changes to the repository, you will need to update your local repository to reflect these changes.

$ git checkout master

$ git pull --rebase=preserve

Downloading Repository Snapshots

As your Git superpowers continue to grow, you will be less likely to download a package from GitHub. This option does exist if you want to share the code with someone who just wants a .zip package (perhaps even for your own project).

To download the .zip package for a project, complete the following steps:

1. Navigate to the project page you want to download the code for.

2. Locate and click the button Download ZIP. This button (Figure 10-12) is conveniently located near the URL for cloning the project locally, or through the GitHub desktop application (which is available for Windows and OS X).

The downloaded package of files will be named according to the project and branch you downloaded. To change which branch you download, complete the following steps:

1. Locate and click the branch drop-down button near the top left of the repository home page (Figure 10-13).

2. Select the branch you would like to download. Wait a moment for the page to refresh.

3. Locate and click the button Download ZIP.

There will not be an indication in the user interface that you are downloading a different branch; however, the filename will reflect the name of the branch (repository_name-branch_name.zip).

Figure 10-12. Download a snapshot of the repository

Figure 10-13. Change the branch you download by first selecting a different branch

Working Locally

Connecting to someone else’s project on GitHub is almost the same process as using your own, except you won’t have write access to the project (unless you are added to the project team, of course). In this section, you will learn how to create a local clone. I use this technique for the Git for Teams website, which uses Sculpin, a static site generator.

In this case, I want a local copy of the Sculpin templates for my site. Although I’m also a volunteer on the Sculpin project, this repository is just for my website. I’m unlikely to have contributions back to the project in the local copy. I do, however, want to maintain a connection to the main project so that I can incorporate the latest updates into my website easily. Although the commands are specific to the Sculpin project, you can substitute the URLs for your project of choice.

The first step is to create a local clone of the project (Example 10-3):

1. Navigate to the project page for the repository you want to download.

2. Locate and click the copy-to-clipboard icon (Figure 10-14) to get the URL for the repository.

3. Open a terminal window (or Git Bash window on Windows) and navigate to the directory where you’d like to download the project to.

4. Create a local copy of the project repository using the command clone and the URL you copied in step 2. Optionally, add the directory name to the end of this command.

5. Change the name of the directory to a name that is relevant to your project. You can optionally do this as part of the previous step by adding the new directory name to the end of the command.

6. Navigate into the local repository.

$ git clone https://github.com/sculpin/sculpin-blog-skeleton.git
$ mv sculpin-blog-skeleton gitforteams.com
$ cd gitforteams.com

The second step (Example 10-4) is to create an upstream, or “vendor branch” that will be kept free from changes relevant only to your project. You will be able to keep this branch up to date with any changes to the main project. For the project I’m working with, the default branch is master. You can choose whatever name makes sense for you; sometimes I use the project name, sometimes I use the generic nickname upstream. I don’t think there’s an advantage of one over the other (although Shakespeare might have said something about my naming whimsies). By moving the branch instead of creating a new one, I maintain the relationship between my local branch and the remote repository. Optionally, if you prefer to work on the master branch, you may recreate the branch master branch.

Figure 10-14. The copy-to-clipboard icon is located immediately above the download button

$ git branch --move master upstream
$ git checkout -b master

The final step is to add a remote repository for your working copy of the project (Example 10-5). This new remote repository will hold all of the changes that you are making for your instance of the project. The Sculpin project shouldn’t keep a record of all the changes I’m implementing for the Git for Teams website, but I need to keep track of them. In real life, I keep the Git for Teams repository on Bitbucket as a private repository. I don’t use the issue tracker, I just toodle away in the repository and upload it after commits, almost like a backup plan. It’s not taking advantage of the features Bitbucket offers, but it does give me peace of mind.

When the project was first cloned, the remote name origin was assigned to the remote repository. We’re going to swap that nickname for upstream, because the convention is to use origin for the repository that most closely mimics our own.

To prepare for adding the new remote, you will need to determine its URL. If you don’t already have a remote repository set up, follow the steps for creating a project earlier in this chapter and ensure the repository does not have any files added during the initialization process. Once you’ve created the new project, follow the on-screen instructions to add the remote information to your repository and then upload the changes. For example, if your GitHub username was gitforteams and your new repository was named superhero-freda, you would add the remote repository as shown in Example 10-5.

$ git remote rename origin upstream
$ git remote add origin https://github.com/gitforteams/superhero-freda.git
$ git push -u origin master

You now have both a branch named upstream and a remote named upstream.

Check the upstream repository regularly for updates (Example 10-6). You do this by checking out the branch you designated as the upstream for the project, and pulling in changes.

$ git checkout upstream
$ git pull --rebase=preserve

Assuming there have been updates to the main project, you can read the changes to see if you want to incorporate them into your own project (Example 10-7).

$ git diff master upstream

Or you can just look for a summary of the specific commits with these fancy parameters added to the command log:

$ git log --cherry-mark --left-right --oneline master...upstream

We’ve seen variations on this command before; the only real new piece is --cherry-mark --left-right. These parameters add a symbol to the beginning of the commit that indicates whether the change was introduced by the first branch on the list (points left), or the second (points right).

Once you have an understanding of the changes, you can bring your own branch up to date with the upstream changes (Example 10-8). This should be completed as if the changes were already in place and your own work was starting fresh today. In other words, you should bring your working branch up to date by rebasing the changes from upstream repository onto your own branch. (As I’ve mentioned previously, if you are working alone, you can also merge the changes in if you find this easier than using rebase. I won’t judge you.)

$ git checkout master
$ git rebase upstream

If conflicts arise, take them one at a time. There are additional tips for dealing with rebase conflicts in Chapter 6.

Tracking Changes with Issues

On public projects, issues are generally opened by users who have uncovered a bug. A much smaller set of contributors will create issues for new features they are interested in contributing, or design changes they are interested in developing.

To create an issue, complete the following steps:

1. Navigate to the project page.

2. Locate and click the tab labeled Issues. It appears on the right sidebar (Figure 10-15). You will be redirected to the issues page.

3. Locate and click the button New issue. It appears on the right side of the screen (Figure 10-16). You will be redirected to an issue creation form.

4. Enter a title, a description of the problem that you want solved (Figure 10-17), and the ticket number of the issue that this pull request is being submitted to solve. The more descriptive you can be about the problem, the more likely it is to be solved.

5. When you are satisfied with your issue description, locate and click the button Submit new issue.

With the issue created, you can now go about creating the pull request that solves the issue.

Forking a Project

If you want to contribute your changes back, complete the following steps:

1. Navigate to the project page.

2. Locate and click the button Fork. The repository will be forked, and you will receive a copy of the repository set up under your own account.

Figure 10-15. Navigation icon for Issues

Figure 10-16. Navigation button to create new issue

You can now clone this copy of the project to your local computer, just as you did in “Personal Repositories”. Once the repository is downloaded, you can make changes to the project, commit them to your repository, and then push them back up to your forked copy of the remote repository.

Once the changes you’d like to incorporate into the main project have been pushed back to GitHub, you are now ready to initiate a pull request.

Figure 10-17. Creating a new issue

Initiating a Pull Request

When you make a fork of a project, GitHub maintains a connection to the upstream project. This allows you to easily send your changes from your forked repository back to the main project.

Complete the following steps to initiate a pull request:

1. Navigate to the project page for your forked repository.

2. Locate and click the button pull request (Figure 10-18). It is located near the top left of the project description, below the title. You will be redirected to a summary of branches that can be used for a pull request. If there are not four drop-down menus displayed, click the link compare across forks before proceeding.

3. From the list of branches, select the branch you want to submit to the upstream project from the final drop-down menu (Figure 10-19). The differences between your branch and the upstream branch will be displayed.

Figure 10-18. The pull request button is located below the project title

Figure 10-19. Choose the branch you want to submit to the upstream project in your pull request

4. Locate and click the button Create pull request (Figure 10-20). A new form will open.

5. Enter a title, and a description for why you are submitting this change to the project (Figure 10-21).

6. Locate and click the button Create pull request to complete your request to have your changes included in the upstream project.

Once you have completed your pull request, the maintainers of the project will be notified through their GitHub interface for the project, and also via email if they have notifications enabled.

Figure 10-20. To initiate the pull request process, locate and click button Create pull request

Figure 10-21. Enter a title and summary that explain the reason for your proposed change

Creating a Project Repository

Most of my public GitHub projects are very tiny—slide decks for various conference presentations and the like. I do not expect to have regular contributors, although I happily accept contributions if people are interested in submitting a new fix. If you are working on a software package, chances are better that others will be interested in contributing to your project. If you are creating a library or software package that you think will be of interest to a larger group, you should not set it up under your personal account, but instead use an organization. By not using your personal account, it will allow other developers to feel a greater sense of ownership over the project, and be more committed to contributing to it.

To create a new project, complete the following steps:

1. From the top menu, click the + symbol.

2. Click on New repository. You will be redirected to the new project form.

3. Beneath the label Owner, click your account and change it to your organization.

4. Enter a repository name. Generally this is the same name as the organization for single repository projects.

5. Enter a terse description for your project.

6. Click Create repository.

Your new repository has been created and you are now ready to begin using it as if it were one of your personal GitHub repositories.

If the project already exists under your personal account, you can reassign it using the following steps:

1. Navigate to the project page under your personal account.

2. Locate and click the link labeled Settings.

3. Locate and click the button labeled Transfer. A modal window will appear.

4. Enter the name of the repository; and the organization, or account name, for the new owner.

5. Click I understand, transfer this repo.

Your project will be reassigned to the new account holder.

Based on your rules of governance, you will now need to decide if you are going to submit yourself to pull requests, or if you will continue to submit your work directly to the project. Both have advantages, but they also follow different leadership models (it is faster to commit directly; but more equal for all contributors if you also submit pull requests, which undergo a review).

Granting Co-Maintainership

To share the burden of maintenance, you can grant write access for the repository to others. This is a big responsibility. You should decide ahead of time how you will deal with the thorny issues, such as disagreement on the direction the code should take; and other types of bad behavior, such as being rude to other contributors. Assuming you have worked through all of those difficult decisions, you can add contributors to your project as follows:

1. Navigate to the project page.

2. From the utility links in the top right of the page, click the + and then choose New collaborator (Figure 10-22).

3. You will be prompted to add your password. Do this and then click Continue.

4. Enter the GitHub username of the person you would like to assign co-maintainership to (Figure 10-23).

Figure 10-22. Navigating to the Collaborators page for your project

Figure 10-23. Adding a collaborator to your project

The person you’ve designated as being a co-maintainer will now have all the same authoring powers as yourself. You may wish to put together a maintenance cheat sheet to ensure you make decisions consistently for all community members.

To remove a collaborator, follow the instructions as outlined previously. Next to the collaborator’s name, click the symbol x (Figure 10-24). The collaborator will no longer have commit access to the repository.

Reviewing and Accepting Pull Requests

Congratulations! You’ve received your first pull request to a project. GitHub provides you with an easy-to-use interface to review incoming pull requests. From here you can add comments to the request, reject the pull request outright, or accept the pull request.

Figure 10-24. Remove contributors from your project

GitHub will notify you if accepting the pull request will result in a merge conflict, and in this case will disable the button to accept the incoming request.

Pull Requests with Merge Conflicts

If the pull request cannot be accepted without a merge conflict, you will be unable to accept the pull request through the Web interface. Instead, you will need to download the branch, resolve the conflict locally, and then push the new branch to the project repository.

The first step is to check out the branch where you want to receive the incoming pull request. For example, you may want to land this into the main branch for your project:

$ git checkout master

Currently your branch doesn’t know anything about the contributor’s repository. You will need to add it as a remote repository before you can download the proposed changes. Instead of using a generic nickname as we have in the past (e.g., origin or upstream), be optimistic and use the contributor’s GitHub username. This will ensure you are ready to accept more changes from them in the future.

In the following example, replace <username> and <repository-name> with the appropriate values for the incoming pull request branch:

$ git remote add username git://github.com/<username>/<repository_name>

With the remote repository added, you must now download the contributor’s work:

$ git fetch username

The branch will now be downloaded and available for local review. You should use the guidelines from Chapter 7 on how to conduct a peer review. You may need to provide feedback to the reviewer and request he or she submit a new pull request if the code isn’t quite right. Refer back to your governance model to see if it’s appropriate for you to make the updates yourself, or if you are required to reopen the issue for further development. A good rule of thumb is this: if the contributors will learn something by doing the work, give them the opportunity to learn. If it’s a silly mistake (a typo, or a coding standard violation), it might make more sense to make the change yourself (still crediting the original author) instead of rejecting a pull request for a trivial fix. Where possible, reduce round-trips the code needs to make, and be respectful of the intentions of the contributor.

When you are satisfied with the proposed change, you can merge it into the main branch for your project:

$ git merge --no-ff username/branch_name

If, however, you would like to make a few cleanup changes for minor whitespace issues, or to fix a typo, you can optionally add the parameter --no-commit. Using this option may not be appropriate for your project if you’ve decided every change must go through the pull request process:

$ git merge --no-ff --no-commit username/branch_name

Regardless of which method you choose, once the branch is merged, you may push the updated master branch up to the server:

$ git push origin master

The change will now appear in the main repository for the project.

If you find you are working with pull requests a lot for your project, and frequently have to deal with merge conflicts, you may find Hub useful. It is a command-line wrapper that allows you to perform more tasks from the comfort of the command line instead of having to switch between GitHub’s web interface, and Git.