Create a new, empty research compendium, starting with an empty GitHub repository

1. Create a new GitHub repository with nothing in it.

Create a GitHub account, confirm your email, then go to https://github.com/new or click on the menu in the upper left of your GitHub home page, as you see in the image:

2. On the next screen, type in the name of your repository.

Take care to choose a memorable name that represents your research, such as some keywords from the title of your manuscript. The name needs to follow the rules for R package names: it can contain only ASCII letters, numbers, and ‘.’, it must have at least two characters, it must start with a letter (not a number), and it cannot end with ‘.’. You can add some text in the description field, and set the repo to be private if you wish. Do not 'Initialize this repository with a README' or add any other files on this page, those will interfere with later steps. Click 'Create Repository' when you are finished here. In this example the repository is public, but you can set it to be private if you prefer, the following steps will be the same for public or private repositories.

3. When your GitHub repository has been created, you will see this page, below.

Select the URL to this page, and copy it so you can paste it later. In this example the URL is https://github.com/benmarwick/demo. At this point, we are finished with GitHub for now, and we will move to work on RStudio on our computer

4. Start RStudio and create a new project

We will download, or clone, our empty GitHub repository into this new project. Click on the new project menu in the upper right to start a new project in RStudio. RStudio projects are helpful because they help us to manage our project's the working directory. This helps to make our project portable (so it works on other computers) and can save a lot of confusion when reading and writing files.

5. Select 'Version Control'

6. Select 'Git'

7. Paste in the URL to your new, empty GitHub repository

We recommend you do not change the 'Project directory name'. If this is different from your GitHub repository name it can cause confusion. You can change the subdirectory location to somewhere suitable on your computer (in this example it is ~/Desktop). You should choose a directory that does not already have an RStudio project file in it because that could lead to confusion. Click the Browse button to select a different subdirectory. When you are finished, click the 'Create project' button.

8. Now we are ready to use rrtools functions to add files and folders to our compendium.

If you don't see the items beginning with a period (.git, etc.), look in the files panel, click 'More' (next to the gear icon), then 'Show Hidden Files', and then you'll see them.

9. Load the rrtools package and confirm that you have Git installed

If you do not see a message like this '✔ Git is installed on this computer, your username is Ben Marwick', you need to stop here and download and install Git, and configure it with your name and email address before proceeding. The free online book Happy Git With R has details on how to do this.

10. Run use_compendium() in your project directory

This will create some files and folders, and print some messages in the console. You may get a question in the console if it is to overwrite your RProj file, you can answer yes. If you want to edit the DESCRIPTION right away, please take a look at this chapter for guidance.

11. Run usethis::use_mit_license(copyright_holder = "My Name") to add a license for your code

To use a different license follow the instructions in the usethis package for other licenses.

12. Run rrtools::use_readme_rmd() to add a readme to give citation information to users

This also adds two other markdown files: a code of conduct for users CONDUCT.md, and basic instructions for people who want to contribute to your project CONTRIBUTING.md, including for first-timers to git and GitHub.

13. Run rrtools::use_analysis()