Introduction to GitHub

What is GitHub?

GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere. GitHub itself is not a development tool, but rather a file hosting and collaboration site. In many ways, a social network like Facebook. You can build a profile, create projects to share with others, and follow the accounts of other users. GitHub is not linked to any one programming language like R, as you can find all kinds of projects based upon different languages there.

GitHub also runs Git in the background. Git is a version control software, which means it records changes to a file or set of files over time so that you can recall specific versions later. We’ll learn more about Git in the next session.

You will need a GitHub account before you can start using it. If you do not have an account already, please see the info here for creating one.

---

Repositories

A repository (or “repo” for short) is a directory or storage space for your projects on GitHub. Repositories can contain folders and files, images, videos, spreadsheets, and data sets. Most repos include a README.md file, which contains information about your project. GitHub makes it easy to add one at the same time you create your new repository. It also offers other common options such as a license file.

Create a repository

1. Log into your account on GitHub.

2. Click on the + sign in the upper right and select New repository.

Name your new repository testing.

Repo names can also use underscores _ and hypens - as text delimiters, if you’d like.

Enter some simple descriptive text in the Description field.

This can be changed later, so don’t worry about its content.

GitHub repos can be set to Public or Private. If set to public, anyone can browse the contents of your repo. If set to private, only you and those you specify as collaborators can view the contents of the repo.

Go ahead and set it to the default Public.

When you create a repo, you have the option of initializing it with a README.md file, a .gitignore file, and a license.

For now, just check the box next to Add a README file.

When you are finished, click on the green Create repository button.

You now have a new repo that is ready to be populated with folders, code, data sets, etc.

---

Markdown

Markdown is a simple markup language for creating formatted text using a plain-text editor. It makes use of some special characters for formatting headers and text. GitHub automatically recognizes Markdown files with a .md extension and renders them as formatted information. The repo we just created has one file in it: README.md, and its contents are displayed at the bottom of the repo.

Writing text

The text in a Markdown document can be formatting in a number of ways. At a basic level, it’s just various forms of text that are converted to nicely formatted features when the file is rendered.

Headings

You can specify different levels of headings using the hash tag (pound) symbol #. By adding more # signs you can decrease the heading level. So, for example, the following

# Level-1 header
## Level-2 header
### Level-3 header
#### Level-4 header

will render to

Level-1 header

Level-2 header

Level-3 header

Level-4 header

Emphasis

Italics

It’s easy to add emphasis to text. For italic face, wrap the text with either a single asterisk (*) or a single underscore (_). For example,

This is *italic*, but then so is _this_.

will result in

This is italic, but then so is this.

Bold

For bold face, wrap the text with either two asterisks (**) or two underscores (__). For example,

This is **bold**, but then so is __this__.

will render to

This is bold, but then so is this.

Bold & italic

For combined bold and italics face, wrap the text with three asterisks (***), such that

This is ***bold and italic***.

renders to

This is bold and italic.

Strike-through

If you want to indicate a deletion or strike-through, just wrap the text in two tilde’s (~~), such that

Oops, ~~this is a mistake~~.

will render to

Oops, this is a mistake.

Block quotes

You can specify a block quote by preceding it with the > symbol, such that

> I have a dream that one day this nation will rise up and live out the true meaning of its creed: 'We hold these truths to be self-evident, that all men are created equal.'

yields

I have a dream that one day this nation will rise up and live out the true meaning of its creed: ‘We hold these truths to be self-evident, that all men are created equal.’

Lists

You can include ordered (numbered) lists, unordered (bulleted) lists, or a combination of the two in Markdown documents as well. Numbered lists simply use a number and period (1.) followed by a space and the text. For example, this text

1. This is item 1  
2. Item 2 comes next

will render to

1. This is item 1
   
2. Item 2 comes next

It turns out that you don’t even have to use consecutive numbers to make it work. For example,

1. This is item 1  
7. Item 2 comes next

will render to

1. This is item 1
   
2. Item 2 comes next

You can specify an unordered list with either an asterisk (*) or dash (-). For example, the following text

* This is a thing 
* Here is another
- And yet another

will render to

• This is a thing
• Here is another
• And yet another

Mixed lists simply use a mixture of the two constructs, such that

1. This is item 1
   * This is a thing
   * Here is another  
2. Item 2 comes next
   - And yet another

will render to

1. This is item 1

• This is a thing
• Here is another
  

2. Item 2 comes next

• And yet another

Links

You can insert links to websites, other files, and other locations within a file. For websites, there are several options. The first is to simply write out the full address inline (eg, http://www.google.com) and it will parse correctly. You can also use shorthand text to hide the full address or make a sentence more readable. To do that, include the name in square brackets followed by the address inside parentheses. For example,

Please conduct your search using [this link](http://www.google.com).

will render as

Please conduct your search using this link.

Inserting pictures

Inline

Inserting links to images works much the same as for websites, but you add an exclamation point (!) at the beginning of the construct (and the text inside the square brackets in optional). For example, here is how to include the hex logo for this class.

![](hexsticker.png)

which will yield this

You can adjust the size of the image by specifying the height and width in percentages within curly brackets. For example,

![](hexsticker.png){ height=30% width=30% }

will yield this

Displaying R code

One of the truly great features of Markdown is the ability to include code within a document. This course uses R, but people also use many other languages in Markdown documents (eg, Python).

Blocks

The most common method for including code in your document is via code blocks, which can be numerous and separated by text, images, etc. Code blocks are delimited at the beginning and end by three back-ticks (```). So, for example, here is a really basic code block

```
a <- 1
b <- 2
```

that would look like

a <- 1
b <- 2

Later in the course when we start using R Markdown, you’ll see that you can execute the code within a document and display the results.

Inline

You can also include code snippets directly within text by surrounding it with single backticks (`). For example,

I assigned the the temporary data frame to the variable `tmp`.

will result in

I assigned the the temporary data frame to the variable tmp.

Edit the README

You can treat the README.md file as a “landing page” for your repo. Because it’s a Markdown document, you can display images, lists, emphasis, etc. Similarly, you could add another README.md file inside a folder within a repo to describe the contents of the folder.

Edit your README.md file by clicking on the pencil icon in the upper right.

This brings up an editing window where you can add or modify existing text using the various formatting options via Markdown. Below you can see where I’ve added some Markdown flavored text.

Add some Markdown to your README.md file.

You can preview a formatted version of your text by clicking the Preview tab.

When you are done editing the text, you need to “commit” the changes. To do so, scroll down to the bottom of the page to the box marked Commit changes.

This is your first introduction to Git. When committing a file, you need to include a “short but informative” commit message to describe the changes you’ve made.

Go ahead and type a commit message in the box and then click the green Commit changes button.

Good commit messages are no more than 50 characters long. (Mark likes to begin his with a past-tense verb.)

Your repo has a newly formatted README.md file.

---

Issues

Issues are used to track to-do items, bugs, feature requests, and more. Some people will refer to these as “tickets” or “cards”. Let’s see how to add an issue to a repo.

Click on the Issues tab in the upper left near the Code tab that you are on now.

At this point the Issues page is empty except for a message from GitHub telling you a bit about Issues.

Click on the green New issue button in the upper right.

Now you will see a window for you to enter details about the issue.

Give your issue an informative title.

It’s common to include some details concerning an issue. For example, you might describe a problem you’re having or a bug you’ve encountered that will need to be fixed later. The issue description can also contain formatted text via the same Markdown we used on our README.md file. Below you can see where I’ve added some details about this issue.

Add some details in the description box.

• You can also make use of the tool bar to help you with formatting, inserting links, etc.

• You can create checkboxes in Markdown with * [ ].

Just like we did when editing the README.md file, you can preview the formatted Markdown in an issue’s description by clicking on the Preview tab.

There are some additional options on the righthand side for assigning collaborators to work on an issue, assigning descriptive labels to the issue to help identify its contents, priority, etc. Notably, these labels are also searchable from the main Issues page.

Click on the Assignees link and then click on your username to select yourself.

Click on the Labels link to see a list of preset labels.

In this case I’ve added the following labels to the issue:

• documentation

• enhancement

• good first issue

When you are finished adding a description, labels, etc, click on the green Submit new issue button at the bottom.

You will now see your new issue as a formatted Markdown document with lots of information about it being “Open”, the labels you added, and another comment box at the bottom.

The checkboxes we added are dynamic and can be checked as tasks are completed.

Click on the Issues tab in the upper left, which will bring you back to the main Issue page.

There are a few things to note here:

• there is now a number “1” inside a circle next to the Issues tab, which means there is one open issue at the moment

• you can filter issues by clicking on the Filters dropdown menu on the left side

• you can use the search bar to the right of the Filters dropdown menu to find specific words or topics

• when there are multiple open issues, you can sort by Author, Label, etc by clicking on the column heading

• you can see there are 3 tasks within this issue below the issue’s title

From here you can add more issues, or click on an existing issue to bring up its details.

---

Projects

Projects in GitHub are a great way to organize your issues, set tasks, track your progress, and work with a team.

Click on the Projects tab at the top of the page.

Here you will see some information about Projects and all of the things you can do with them.

Click on the green downarrow next to the Link a project button on the right and select New project. Then click the green New project button.

If this is your first project, you should see a welcome window like the one below.

Click on the green Jump right in button.

You should now see a pop-up window for selecting a template with Table as the default.

Click on Board on the the left side and then click the green Create button.

You now have an untitled and empty project template with 3 gray boxes labeled Todo, In Progress, and Done.

Click on link at the top labeled @username’s untitled project (where username is your GitHub username) to bring up the project settings.

On the Project settings tab you can add a name, description, and README.

If you scroll down you will see the Danger zone where you can change the project visibility from private to public, close the project, or delete it.

Scroll back to the top and add a project name and description. Click the green Save button when you are done.

Now add some text to the README and click the green Save button when you are done.

Just as with other README sections, you can use Markdown for emphasis, lists, links, etc.

You can click on the Manage access link on the left to open up the project access tab. Here you can invite collaborators and set their role.

You can click on the Status link on the left to open up the field settings tab, which allows you to rename the column headings in your project or add other columns/fields as well.

Click on the left arrow in the upper left to return to your project’s main page.

Your project now has a better name.

Click on the + Add item link at the bottom of the Todo field.

Click on the link to Add item from repository.

Select testing from the dropdown menu and then check the box next to the Issue you created earlier. Click the green Add selected items button when you are done.

Click on the X in the upper right to return to the project board.

You now have a new project with one todo item.

You can click on the issue title in the todo column to see its details. Click on the X in the upper right to close the preview window.

Now let’s address our todo items in our open issue.

Click-and-drag the issue from Todo to In progress.

Click in the Search or jump to… box at the top and select your testing repository to take you back there.

---

Adding files and folders

Let’s address our open issue by adding some more content to our repo. To do so, we’ll work entirely within GitHub, but later in the course we’ll see how to add files from other locations like a local directory on your computer.

Click on the Add file button next to the green Code button and then select Create new file.

We now have a window for editing the file contents similar to the one we saw earlier when editing our README.md file. At the top left is a box where you can type in the name of the file you’d like to create.

If you’d like to create a new file within a new folder, you begin by typing the folder name followed by a / and then file name. You’ll notice that as soon as you type the / after the folder name that GitHub will automatically shift the text box to focus on the file name.

Create a new R script within a folder called R, and name it 00_testing.R.

Navigate to the editing box and add some simple R code (it doesn’t matter what code you add).

When you are finished, scroll down to the Commit new file area, enter a brief but informative commit message, and click on the green Commit new file button.

You can now see the contents of the new /R folder, which at the moment contains only the new 00_testing.R file we just created.

In addition to the file name, you can see the commit message you used when committing the file (“created test R script for demo”) and when the file was committed (“now”).

You can click on the file name to inspect the file’s contents.

Click on the Code tab in the upper left, which will take you back the repo’s main page.

Here you can see our new R folder just above our existing README.md file.

Now let’s add a simple data file called example_data.csv and place it within a new folder called data.

Click on the Add file button next to the green Code button and then selecting Create new file. Type the folder name and file name in the box and add the following information in the editing box (you can copy and paste if you’d like):

last_name, first_name, role
Scheuerell, Mark, instructor
Adams, Mary, TA
Manion, Lance, student

When you are finished, scroll down to the Commit new file area, enter a brief but informative commit message, and click on the green Commit new file button.

Just as when we created our R script within the /R folder, you can now see the new example_data.csv file we just created within the /data folder.

Click on the Code tab in the upper left, which will take you back the repo’s main page where you will see the new /data folder just below our existing /R folder.

---

Closing an Issue

Now that we’ve added some new folders and files to our repo, let’s return to the Issue we created earlier and “close” it.

Click on the Issues tab on the top of the page to take you back to our open issue.

Click on the issue’s title, which will open it up and show you all of the details.

Check the boxes next to the 3 open tasks.

As you check off boxes next to tasks, GitHub will automatically update the number completed under the issue’s title.

At the bottom of the issue you will see a comment box with two buttons below it: Close issue and Comment. You don’t need to add a comment when closing an issue, but it’s often helpful to do so.

Add a comment and then click the Close with comment button.

You’ll now see that GitHub has marked the issue with a purple “Closed” label under the issue name.

Click on the Issues tab to return to the Issues page where GitHub informs you that there aren’t any open issues.

Closing a project

Let’s return to our project and check on our progress now that we’ve closed the open issue.

Click on the Projects tab to take you back to the main Projects page where your project is listed and then click on the project name to open it back up.

GitHub automatically moved the open issue to the Done column when you closed it earlier.

Endnote

Congratulations!

You’ve now successfully done the following:

• created a new repo on GitHub

• edited your README.md file

• created an issue

• created a project

• added some additional content to your repo

• closed an issue

• managed your project