GitHub Setup Tutorial

Get Started with GitHub

GitHub Hierarchy

GitHub consists of a local workspace (a set of working directories on your local computer) and a remote workspace (a set of working directories on an external server, known as the GitHub repository).

The local and remote workspaces each consist of the following three directories:

  • Working directory

  • Staging directory

  • Repository directory (also sometimes referred to as the HEAD directory)

Common GitHub Workflow

GitHub offers flexibility for users to create and implement many possible workflows. For example, many developers use the following simple workflow:

  1. On their computer, in the local environment, a developer changes or creates a file in the working directory.

  2. When the changes are complete, the developer wants to save and push those changes to the GitHub repository. To accomplish that, they will need to stage the files. They can do this by running the add command, to add the files to the Staging Directory.

  3. After staging the files, the developer will want to move the files to the Repository (HEAD) Directory. They will do that by running the commit command.

This workflow can be summarized as follows:

  1. Working Directory—Files are created or edited.

  2. Staging Directory—Files are added using the add command.

  3. Repository (HEAD) Directory—Files are committed using the commit command.

Understanding this important distinction of where files exist at any given time (local vs. remote) is critical to managing files on your local computer and on the remote GitHub repository.

Important: Remember, files that have been committed and moved to the Repository (HEAD) Directory are still only present on your computer in your local repository!

Ultimately, the goal is to push the files out to the remote GitHub repository so that other developers on your team can view and edit the files. You can use the following commands to move files:

  • Use the push command to move files from your local Repository (HEAD) Directory to the remote GitHub Repository (HEAD) Directory.

  • Use the pull command to move files from the remote GitHub Repository (HEAD) Directory to your local Repository (HEAD) Directory.

To determine which files exist on your local directory vs. the remote GitHub directory, remember the following:

  • When logged into your GitHub UI, you are viewing files in the remote GitHub repository.

  • When browsing files in your computer file directories, you are viewing your local environment repositories.

Files can have the following three possible states:

  • The file is in your local repository AND in the remote repository.

  • The file is in your local repository but NOT in the remote repository.

  • The file is in your remote repository but NOT in the local repository.

Note: In this boot camp, you will learn numerous ways to determine whether files on your computer are also on the GitHub repository. Just remember that you can always quickly and easily compare file status between the local and remote repositories by logging in to the GitHub UI and comparing those files to your local computer repository.

GitHub Guide

Create a Project in the GitHub Repository and Clone to the Local Workspace

  1. On the GitHub UI, navigate into the Repositories tab and click the New button to create a new repository named github-test-project.

    • Choose the default option to give the repository Public access.

    • Under Initialize this repository with, select Add a README file and Add .gitignore.

      • When you select Add .gitignore, a dropdown menu will offer options for .gitignore templates. Select Java to generate a Java .gitignore file.

    • When you're ready, select Create repository.

  2. The github-test-project has been created! Note that the repository contains two files—the .gitignore file and the README.md file.

  3. Next, locate the Code button and select the dropdown arrow. From the dropdown menu, select HTTPS, and click the copy icon to copy the repository URL to your clipboard.

  4. From your terminal window, navigate to your workspace folder. Here you will run the Git clone command, to copy the repository onto your computer in your workspace directory.

    • From inside your workspace directory, enter the command git clone [REPOSITORY_URL], where [REPOSITORY_URL] is the URL that you copied to your clipboard in the preceding step.

      • Windows users: note that the Ctrl+V and Ctr+C shortcuts do not work for copy and pasting in Git Bash. To paste the URL that you copied to the Git Bash terminal, use the Insert key.

      • As the cloning process begins, a message will indicate that the project code is being copied from the remote GitHub repository to your local workspace folder (something like Cloning into github-test-project...).

  5. After the cloning process completes, run the command ls -a from inside your workspace directory. Running this command should reveal the github-test-project folder and confirm that the project has been copied into your workspace directory.

  6. Next, change directories to navigate into the github-test-project folder, by running the command cd github-test-project.

  7. Having navigated into the github-test-project directory, run the command ls -a. This time you will find a few files, including the README.md and .gitignore files that were created on the repository when you created the project on the GitHub UI.

    • The .gitignore file is a hidden file, as indicated by the dot (.) preceding the file name. But the -a in ls -a allows us to view hidden files from the terminal!

  8. Next, let's confirm that your local github-test-project folder is in sync with your remote GitHub github-test-project folder, by running the command git status from inside the github-test-project directory.

    • A response should indicate that you are On branch main and that Your branch is up to date with origin/main.

    • This tells us that the files in the local github-test-project directory match the files in the remote GitHub github-test-project directory. The local repository and the remote repository are in sync!

  9. Next let's create a new file in the local github-test-project directory, by running the command touch TestFile.

  10. Confirm that the new file was created—by running the ls -a command—and confirm that there is now a file named TestFile in your local repository.

  11. At this point we should expect that the newly created file is in the local repository but not in the remote GitHub repository—indicating that the local repository and the remote repository are out of sync.

    • To confirm this, refresh the GitHub UI. Note that we find no reference to any TestFile in the UI view.

  12. In the terminal, from inside the github-test-project directory, run the command git status.

    • Once again, a response should indicate that you are On branch main and that Your branch is up to date with origin/main. However, this time you should also find a reference to Untracked files:, with TestFile listed in red text. The red text indicates that this file is now present in your local Working Directory.

    • Remember, to move this file from the Working Directory to the Staging Directory and then to the Repository (HEAD) Directory, we will need to add the file to the Staging Directory and then commit the file to the Repository (HEAD) Directory. Let's do that next!

  13. To move the file from the Working Directory to the Staging Directory, run the command git add TestFile from inside the github-test-project directory.

  14. Now run the git status command.

    • Note that this time TestFile is listed in green text—indicating that the file is now staged in the Staging Directory and is ready to be committed.

  15. Next, run the command git commit -m "[COMMIT_MESSAGE]".

    • The -m portion of the command indicates that you will commit the file and leave a message to describe the commit. For example, git commit -m "Adding TestFile to the repository".

    • Remember that the commit command will move the file from your local Staging Directory to your local Repository Directory. The file is still on your local computer but not yet present in the remote GitHub repository.

  16. Next we will want to push the file from the local Repository (HEAD) Directory to the remote Repository (HEAD) Directory. To do so, execute the following commands:

    • Run the git status command, and note that the response indicates that Your branch is ahead of origin/main by 1 commit.

    • Now it is time to push the file up to the remote GitHub repository, by running the command git push.

  17. Confirm that the push command was successful by refreshing the repository page in the GitHub UI.

    • Previously we confirmed that TestFile was in the local repository but NOT present in the remote repository.

    • Now, after refreshing the repository page in the GitHub UI, you should find TestFile listed along with the README.md and .gitignore files—confirming that the push command was successful. The local repository and the remote GitHub repository are once again in sync!

Pull Changes from the Remote to the Local Workspace

Now that we have created a file on the local repository and then pushed that file out to the remote GitHub repository, let's explore the opposite situation—when we pull a change from the remote repository into the local repository.

  1. Select TestFile in the GitHub UI. Then locate and click the trash can icon, to delete TestFile from the remote GitHub repository.

    • When you click the trash can icon, a new page will open and ask you to commit the changes. Enter a description for the commit in the text area provided, then click Commit changes to commit the deletion of TestFile.

  2. You should be returned to the main repository page after clicking the Commit changes button. Now you can confirm that the TestFile is no longer listed as a file on the remote GitHub repository—meaning that the remote GitHub repository and the local repository are out of sync again.

  3. To confirm this, go back to the terminal and run the command ls -a from the github-test-project directory. You should still find TestFile in your local repository, confirming that the remote and local repositories are out of sync.

  4. Next, from the github-test-project directory in your local environment, run the command git pull to pull the changes from the remote GitHub repository into your local repository.

    • In this example, that change is represented by the deletion of the TestFile from the remote GitHub repository.

    • When you run the git pull command, you should find that TestFile has been deleted.

  5. Once again, run the ls -a command from inside the github-test-project directory, to confirm that TestFile has in fact been deleted and removed from the local repository.

    • At this point, the local repository and the remote GitHub repository are in sync!

Congratulations! You have now successfully created a GitHub repository, cloned that GitHub repository to your local workspace, made changes to the files on your local workspace, and pushed those changes up to the GitHub repository—successfully re-syncing the local and remote repositories. Then you made changes to the remote GitHub repository and pulled those changes into your local repository—again, successfully re-syncing the local and remote repositories.

These GitHub skills will prove to be valuable for this course as well as your professional software development career!

Personal Access Token Overview

Compared to password authentication, tokens offer numerous security benefits. For one thing, they are unique and random, helping to prevent brute force attacks. We can also limit their scope depending on needs, and we can revoke them individually without updating other credentials.

Token Setup Guide

To complete the following steps, you'll need to sign up for an account on the GitHub website if you haven't already:

  1. Click your profile image in the top-right corner of the GitHub website, and choose Settings from the dropdown menu.

  2. Scroll down and select Developer settings on the left, as shown in the following image:

    A screenshot displays various options under the Settings menu, including Developer settings.

  3. Then click Personal access tokens from the left, as shown in the following image:

A screenshot shows the Personal access tokens option under GitHub Apps.

  1. Click Generate new token in the upper right, configure for No expiration, and check the repo box for full control of private repositories, to match the following image:

    A screenshot displays the New personal access token page, with the no expiration and repo options selected.

  2. After generating the token, leave the page open. You will need to use the token for authentication in a later step.

Next, follow these steps in your command line:

  1. Checkout the branch you want to push to GitHub.

  2. Run git push origin <branch_name>, pushing your local branches to your shared repository.

  3. When you receive the Username for 'https://github.com': prompt, enter your GitHub username.

  4. When you receive the Password for 'https://<username>@github.com': prompt, copy and paste your personal access token from the GitHub window left open in the previous step.

  5. You have now pushed the local branch to GitHub, allowing your teammates to access it later!

  6. Checkout the main branch and then run git pull.

  7. Show students the output and explain that if anyone else had committed and pushed changes to the remote repository, git pull would update their local repository with those changes.

Nice work! As you will learn, GitHub is a collaborative tool—you can pull any changes down to your local repository quickly and easily, allowing you to easily share different versions of your code across workstations and to easily checkout and test those versions on your local computer.