Digital Scholarship Resources - Vanderbilt Libraries Digital Scholarship and Communications Office
Previous lesson: GitHub introduction
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
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.
Branches are a working version of a project. Commits are snapshots of the history of the branch at a given moment in time.
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.
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:
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.
Note: As of 2021, GitHub has changed the default branch name to
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.
GitHub Desktop Client download link
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.
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.
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.
.gitignore, and generate a
README.mdfile and make at least one commit using the web editing interface.
README.mdfile, but don’t worry if you can’t (we will do that in the next lesson).
Next lesson: GitHub work cycle
Questions? Contact us
License: CC BY 4.0.
Credit: "Vanderbilt Libraries Digital Scholarship and Communications - www.library.vanderbilt.edu"