Digital Education Resources - Vanderbilt Libraries Digital Lab

Previous lesson: GitHub introduction

GitHub for beginners: Setup

This lesson demonstrates how to set up a GitHub repository and clone it to a local computer using GitHub Desktop Client.

Learning objectives At the end of this lesson, the learner will:

Total video time: 34 m 52 s

Lesson slides

Setting up a GitHub account and creating a repository (6m28s)

Once you have an account you can create a new repository through the + menu in the upper right of the screen.

In the create repository dialog, you have several choices. The most important is whether you want the repo to be public or not. There are also three special files that can live in the root directory of the repository. One is the .gitignore file. A .gitignore file is not required, but if you are using a coding platform that generates a lot of annoying extraneous files that you don’t want to archive in GitHub, you can select a template .gitignore file for that platform that will ignore typical annoying files.

If your repository is public, you should add a license file that is appropriate for the kind of content you will create in the repository. If you are creating code and you want it to be open, many people use the MIT License. You can pick it or any other license from the dropdown list. If you are creating textual content that you want to be usable by anyone, but with attribution, a Creative Commons Attribution (CC BY) license is commonly used. It is not on the dropdown list, but the license file can be copied from here.

The third special file is called README.md. When a repository or directory within a repository has a README.md file, it will automatically display when the repository or directory is opened on the GitHub website. So it’s an important way to let potential users know the purpose of the files in that directory. When you’ve set up everything, click on the Create repository button.

After you have created the repository (or clicked on a repository name in the repository list for your account), you’ll see the list of files in the repository. If you created a README.md page, it will also be displayed at the bottom of the page. To create a new file using the online file editor, click the Create new file button. You’ll be at the same screen if you click on a file name, then click on the pencil icon at the upper right.

Commits (2m33s)

Branches are a working version of a project. Commits are snapshots of the history of the branch at a given moment in time.

branches diagram

In a version control system, it is possible to revert to a particular commit of a branch if things go badly. You can also compare the differences between two particular commits to see how the project has changed. That kind of comparison is called a diff.

Markdown (3m22s)

Here is the basic Markdown formatting syntax shown in the examples. Note that inline code is done with a backtick (the key in the far upper left on most U.S. keyboards). It is NOT a single quote.

# level 1
## level 2
### level 3

*italics*
**bold**
`inline code`

- item 1
- item 2
- item 3

[link text](http://vanderbi.lt/github)

| header1 | header2 |
| --- | --- |
| row1cell1 | row1cell2 |
| row2cell1 | row2cell2 |

Here is what the Markdown above looks like when rendered:

level 1

level 2

level 3

italics bold inline code

link text

header1 header2
row1cell1 row1cell2
row2cell1 row2cell2

This website is rendered with a theme, so the exact appearance may vary somewhat from how it would be rendered elsewhere. For example, the bullets in this theme default to yellow arrows rather than the usual dots. The shading and style of tables also varies.

There are many sources of information about Markdown online. A useful general cheatsheet for GitHub flavored Markdown is here.

Committing online (9m36s)

Note: As of 2021, GitHub has changed the default branch name to main.

When using the web editing interface you can make direct commits to a branch in the online repository.

When you’re editing a document in the online editor, you type after clicking the Edit file tab. If you click on the Preview changes tab, you can see how your file has changed since the previous commit. Text that’s been removed is shown in red and new text is shown in green. Each time you make a commit, you are required to enter a commit summary. Optionally, you can also add more detailed comments.

Although typing a commit summary is annoying, it is important because it makes it possible to get an overview of how the branch has changed over time. That’s crucial for two reasons. In the unhappy situation where you need to revert back to an earlier commit, it will be the easiest way to find where that commit is. The commit history also allows other collaborators to understand the series of changes you made in a branch when examining a pull request and deciding whether your work should be incorporated in the main branch. (More on pull requests in a future module.)

Once you’ve made the commit, you’ll see a summary of the file contents. If you click on the History button, you can see the history of commits.

The commit history shows all of the commit summaries for commits that have affected this particular file in the past. The button to the right of the commit summary allows you to see a “diff” that compares how every file in that commit had changed since the previous commit.

Installing GitHub Desktop (2m33s)

GitHub Desktop Client download link

Cloning a repository (6m38s)

You can initiate cloning of a repository from the website by clicking on the Clone or download button in the upper right of the repo page on the GitHub website. If you choose Open in Desktop, the repository will open in the GitHub Desktop software after it downloads.

You can also initiate the cloning process from your local computer from within the GitHub Desktop application. The process described here will work for cloning one of your own repositories, a repository that you’ve forked to your account from elsewhere, or another repository that you don’t own, but to which you have been given write access.

Drop down the Current Repository menu in the upper left of the window. Click on the Add dropdown and select “Clone Repository…”.

You’ll be presented with a list of repositories at Github.com to which you have access. Repos that you own or to which you have write access will show up with little book icons. Repos that are forks you’ve made of some other user’s repo will have a little “fork” symbol. Click on the name of the repo you want to clone and you’ll have an opportunity to select the directory where you want the local copy of the repo to live on your computer. Once you’ve selected a location, the desktop client will default to that location the next time you clone.

Note to Windows users: In some cases, computers are set up so that the default Documents folder points to some location other than the Documents folder within the user folder (for example on a file server elsewhere). In that case, there may be confusion about the location of files managed by GitHub Desktop when the GitHub directory is installed in the default location within the Documents directory. For that reason, it may be advisable to have the Desktop client locate the GitHub folder directly inder the root of the c: directory. That makes it easy and unambiguous to find the repository directories using File Explorer or through the Command Prompt.

After you’ve finished the cloning process, in the left column of the client, you’ll see either changed files or the commit history, depending on which tab you’ve selected. The second column (“Current Branch”) will normally be set at “master” unless you have created another branch.

Code editors (3m42s)

There are many excellent free code editors available that can help you more easily edit documents and scripts in many languages. Two will be mentioned here: Atom and Visual Studio Code (not part of Microsoft’s Visual Studio IDE). They are not necessarily better than all the others, but we have experience with them and can recommend them. Both editors are available for Mac, Windows, and Linux, so if you get used to one, you can continue to use it if you change platforms at some time in the future.

Syntax highlighting

All good code editors provide syntax highlighting based on the particular programming language of the file you are editing. Editors generally figure out the language you are using from the file extension of the file. So for example, if you open a file that has the extension .py (the usual file extension for Python scripts), the editor will provide highlighting specifically for Python. If you open a new file and start typing, the editor will not know what kind of highlighting to use until the first time you save the file. So usually you will want to save the file with the correct extension as soon as you start writing the code.

Here’s what syntax highlighting looks like in Atom for a Python script:

Here’s what the syntax highlighting looks like for the same script in Visual Studio Code:

Installing the editors

To install Visual Studio Code, go to https://code.visualstudio.com/. You browser should detect your operating system and suggest the correct download for it.

To install Atom, go to https://atom.io/. You browser should detect your operating systme and suggest the correct download for it.

Practice assignment

  1. Create an online GitHub repository. Select a license, .gitignore, and generate a README.md file.
  2. Edit the README.md file and make at least one commit using the web editing interface.
  3. Examine the commit history using the web interface.
  4. Clone that repository to your local computer’s drive using GitHub Desktop. Be thoughtful about where you want the repository to go on your local computer drive because it will be harder to change the default location later.
  5. Look at the local repository history in GitHub Desktop and find the commit you made in the cloud.
  6. Using your system’s file directory application (Finder on Mac, File Explorer on Windows), navigate to the repository directory. See if you can figure out a way to open the README.md file, but don’t worry if you can’t (we will do that in the next lesson).

Next lesson: GitHub work cycle

Revised 2022-01-24

Questions? Contact us

License: CC BY 4.0.
Credit: "Vanderbilt Libraries Digital Lab - www.library.vanderbilt.edu"