Our First Repository

If you’ve been following along with the last two posts, you should now have a basic idea of what GitHub is and how it works, and you should also have the infrastructure in place to start using it. Now let’s create our first repository. Open GitHub Desktop and click the blue “Create a tutorial repository…” button at the top of the left-hand column.

Then click “Continue” in the dialog box that shows up. You will be prompted to authorize GitHub Desktop to access your GitHub account; as in the previous post, click the green button to authorize. You may need to reenter your GitHub password. You will then be taken to the screen below:

The first step when using GitHub is to create a branch. You can see in the toolbar at the top of the window that one branch, main, has already been created for us. This is the default branch for our repo. In a repository containing executable application code, the main branch is usually the most recent stable version of the application. For this reason, you should never make changes directly on the main branch. Instead, changes should be made in feature branches. To create a new feature branch, click on the “Current branch” dropdown at the top of the window and then click “New branch,” or use the keyboard shortcut Ctrl-Shift-N.

At the dialog box, give the branch a name and then click “Create branch.” The branch name may contain only alphanumeric characters and hyphens. Now use the keyboard shortcut Ctrl-Shift-A to open the repository in a text editor. On Windows, the text editor defaults to Visual Studio Code. In the left-hand sidebar of the VS Code window that opens, double-click the file README.md. You will see the following default content:

Enter your name on the blank line at the bottom of the file, use the keyboard shortcut Ctrl-S to save the file, and then close VS Code and go back to GitHub Desktop. You should see something similar to the following:

Notice that in the left-hand sidebar, we now see the README.md file listed as having been modified since the last commit (note: GitHub Desktop automatically performed an “initial commit” when it created the README.md file). In the main part of the window, we can see GitHub Desktop pointing out for us the specific changes that have been made since the last time the file was committed. Insertions will appear with a green background, as you can see, and removals will appear with a red background.

Up to this point, the changes we have made are not yet committed to the repository; that is, they are not yet a part of the version history being maintained by Git. Changes that have not yet been committed are much easier to reverse than committed changes, so it is wise to review the changes to each file before committing them to make sure there are no typos. (Committed changes can be backed out later, but this can get messy depending on how long ago the change was made, so we’ll wait to address that topic until later.) When you are sure the files are ready to be committed, type a brief summary of the changes in the “Summary” box at the bottom of the left-hand sidebar and then click “Commit to branch-name-here.” Once you commit your changes, they are part of the version history in your local copy of the repository. In order for other contributors to see these changes, you must push them to the copy of the repository being maintained on GitHub.com. To do this, click “Publish branch” at the top of the screen or use the keyboard shortcut Ctrl-P.

The changes made to the file are now pushed to the GitHub.com copy of the repository on the branch we created. Once you are confident that the updated version of the code is stable, you can ask to have your changes copied over to the main branch by opening a merge request (also sometimes called a pull request). To create a merge request for the change we just made, use the keyboard shortcut Ctrl-R. This will open GitHub.com to the merge request form. Type a short description of your changes in the text box and then click the green “Create pull request” button.

After creating the merge request, you should be taken to a page where you can view the request. You should see a message that says “This branch has no conflicts with the base branch,” and below it, a green button to execute the merge.

Click the button, and then click the “Confirm merge” button that appears. You should see the message “Pull request successfully merged and closed.” Click the “Delete branch” button next to the success message – now that the changes made on our feature branch have been copied over to the main branch, we don’t need the feature branch cluttering up our repository.

Now we just have one last task: updating our local copy of the repository to reflect the merge we performed on the GitHub.com copy. Go back to GitHub Desktop. Click the “Current branch” dropdown and select the main branch, then click the “Fetch origin” button at the top of the screen, or use the keyboard shortcut Ctrl-Shift-P. Your local copy of the repository is now back in sync with the remote copy.