Minimal Setup with Github Desktop

GitHub Account:

* If you don’t have a GitHub account, please create one here: github.com/join

* !! Your username will be visible in your GitHub project (repository) URLs.

* Remember your username and password.

To use Git on your local computer, you need to have Git installed. By installing GitHub Desktop, a Git version gets also installed. Git can also be installed as a standalone version. Here, it’s easiest to install GitHub Desktop, and get Git automatically with it. In addition, GitHub Desktop uses an easier authentication than standalone Git versions (but you won’t get the full integration in RStudio without installing a standalone version).

(Optional: to check whether Git is already installed, go to Verify Local Git Installation)

Is GitHub Desktop already installed on your computer?

Check by typing ‘github’ in the Windows search bar. If installed, Github Desktop will show up as a match.

1. Installing and Setting Up GitHub Desktop

Getting started with GitHub Desktop is a straightforward process.

Download the Application: Go to the official GitHub Desktop website https://desktop.github.com/download/ and download the installer for your operating system (Windows or macOS).

On LJMU managed computers:
- Move the downloaded .exe file from ‘Downloads’ to ‘C:\temp’
- Click ‘Install anyway’ when prompted
Install and Launch: Run the installer and follow the on-screen prompts. Once installed, the application should launch automatically. If not, start it yourself.
Sign In: You’ll be prompted to sign in to your GitHub.com account. Use your GitHub.com credentials. This might be automatically skipped if you are already logged in to GitHub.com.

This is a crucial step that connects the application to your online repositories. If you don’t have an account, you’ll need to create one first on the GitHub website, or follow the prompt.

2. Using GitHub Desktop with a New RStudio Project

This is the easiest way to start a new project. You’ll create the repository on GitHub and then clone it to your computer.

Create a New Repository: In GitHub Desktop, click File > New Repository….
Name Your Project: Give your new repository a clear and descriptive name (e.g., my-first-r-project). Check the box to “Initialize this repository with a README.”
Create repository: Click Create Repository. GitHub Desktop will create the local repository in the folder you specified. !! To just work locally, with version control, you could stop here. However, to backup your repository remotely, click Publish repository. This will publish/push the new repository, i.e. the new folder with all its contents to your GitHub account.
Create RStudio Project: In RStudio, go to File > New Project…. Select Existing Directory and navigate to the folder that GitHub Desktop just created for you. Click Create Project.
Initial Commit: RStudio will now be linked to your Git repository. You’ll notice a Git tab in the top-right pane. Back in GitHub Desktop, you’ll see that a new .Rproj file has been added.

Work on your files in RStudio, save them, then switch to GitHub Desktop when you want to commit and push, as follows:

In GitHub Desktop, in the ‘Summary’ text box on the left, write a short commit message like “Add RStudio project file” and click Commit to main. (It might say ‘Commit 2 files to main’ if the .gitignore file was added. That’s ok!) Note that all changed files have been staged already by GitHub Desktop (i.e. they have a tick mark next to them and are selected).

!! If you commit here for the first time, you should be asked about the user name and email address to use:

Your Name can be your GitHub user name, but doesn’t have to be. This is what appears as the author of your commits on GitHub.
User email has to be an email address connected to your github.com profile. These can be found on github.com, by clicking on your profile picture -> Settings -> Emails. You can use your actual email address, or, more standard, there is a more anonymous email that can be used (look on that page for the email address ending in @users.noreply.github.com). This is the email that will probably be suggested automatically.

Push to GitHub: Click the Publish repository button to upload these changes to your online GitHub repository. Keep all default options.
You can now view your linked GitHub repository online. Just click on the View on GitHub button in the main GitHub Desktop window. A browser window will open.

3. Connecting an Existing RStudio Project

If you’ve already started working on a project in RStudio and want to add it to GitHub, here’s the workflow.

Add a Local Repository: In GitHub Desktop, click File > Add Local Repository….
Navigate to Your Project: Select the folder that contains your RStudio project.
Publish Your Repository: Click Add repository. An error message will appear, asking you to create a repository here instead. Proceed with this option, with the default settings (check the ‘initialize with a README’ file if you like). Once created and added, you’ll see a blue button that says Publish repository. Click it.
Name and Publish: A window will pop up to let you name the new repository on GitHub. Once you’ve chosen a name, click Publish Repository.
Initial Commit: All of your project’s existing files are now ready to be committed in GitHub Desktop. Write an initial commit message like “Initial project files” and click Commit to main.
Push to GitHub: Click the Push origin button to upload your project to GitHub.
Now, every time you change your code in RSTudio or add a file to your RStudio project, those changes will show up in the GitHub Desktop ‘Changes’ log on the left.

4. Recap: Standard Workflow - Commit & Push

This is the normal process you’ll use with GitHub Desktop.

Make Changes: Work on your code or documents within RStudio as you normally would.
Open GitHub Desktop: After saving your files in RStudio, switch to the GitHub Desktop application.
Review and Stage: GitHub Desktop will automatically show you all the changes you’ve made. You can review and select the files you want to include in your commit.
Write a Commit Message: In the bottom-left of the application, write a short, descriptive commit summary. For example, “Add data cleaning script” or “Fix error in ggplot function for Fig 3a”. A good commit message explains what you changed and why.
Commit and Push: Click the Commit to main button. This saves the changes to your local Git history. Then, click Push origin to send those changes to your online GitHub repository.

5. Collaborating with a Student

To allow a student to collaborate on your repository, you first need to invite them to the project on GitHub.com.

Invite Collaborator: On the GitHub website, navigate to your repository (or just click the ‘View on GitHub button in GitHub Desktop). Click on the Settings tab, then Collaborators. From there, you can invite your student using their GitHub username, full name, or email address (’Add people’).
Student Accepts Invitation: The student will receive an invitation email. They must accept the invitation to gain access.
Student Clones the Repository: The student should open GitHub Desktop and go to File > Clone Repository…. They will see your project in the list of their repositories and can select it to clone it to their own computer.
Student’s Workflow: The student’s workflow is similar to yours, but with one key difference: they should Pull before they start working. This ensures they have the latest version of the code. The complete cycle for them is:
- Pull any new changes from the main repository.
- Make changes in RStudio.
- Commit their changes with a descriptive message.
- Push their committed changes to the main repository.

From here, go to the Complete RStudio/Git workflow or go more in depth below with the current setup.

Optional

6. Working with Branches (best practice, but not essential, especially for <2 users of the same repo)

Working directly on the main branch can be risky, especially in a collaborative project. A branch is a separate version of your project that allows you to work on new features or bug fixes without affecting the main code.

A branch is essentially a small, movable pointer to a specific commit. When you create a new branch, you’re not creating a full copy of your project’s files (there’s no separate folder for each branch). Instead, you’re creating a new pointer that initially points to the same commit as the branch you branched from (e.g., ‘main’).

Commits: Each commit is a snapshot of your project at a particular point in time. It contains a unique identifier (a hash), metadata (author, date, message), and a pointer to its parent commit. This forms a history of changes.
Branches: A branch is simply a name that points to one of these commits. When you switch to a branch, Git updates your working directory to match the state of the files at that commit.

When you make a new commit on a branch, Git creates a new commit and then updates the branch pointer to point to this new commit.

Create a New Branch: In GitHub Desktop, at the top of the application, click on the Current Branch dropdown menu and select New Branch…. Give your branch a descriptive name (e.g., add-new-data, fix-plot-bug).
Switch to Your New Branch: The application will automatically switch you to this new branch.
Make and Commit Changes: Make all of your changes and commits on this new branch. This keeps them separate from the main branch.
Publish the Branch: The first time you commit to a new branch, you’ll need to Publish branch to make it available on GitHub.com.
Create a Pull Request: Once you are done with your work, go to the GitHub website. You will see a prompt to create a Pull Request. A Pull Request is a request to merge your changes from your new branch into the main branch. This is the perfect time to ask your collaborator for a review or to check for any conflicts before merging.
Merge into Main: When your work is ready and reviewed, you can merge your branch into main. In the Pull Request on GitHub.com, click the Merge pull request button. The changes are now safely integrated into your main project.
Clean Up: Once merged, you can delete your branch from both GitHub.com and GitHub Desktop to keep your project clean.

6.1 Collaboration Best Practices on Branches

For a smooth collaborative workflow, it’s essential that everyone follows a few best practices.

Start with the Latest Code: Before a student begins any new work, they should always Fetch origin and Pull origin on their main branch to make sure their local version is up-to-date with the shared repository.

Fetch just imports all the updated files and the commit history, without merging it with any local files.
In contrast, Pull is a combination of Fetch and Merge: It downloads the changes and then attempts to integrate them into your current local branch.

Branch for Every Task: Encourage your student to create a new, separate branch for every new feature, bug fix, or major change they work on. This keeps their changes isolated and makes it easy to review and merge their work without disrupting the rest of the project.
Use Pull Requests for Feedback: The Pull Request is the central tool for code review. As a tutor, you can review the student’s code, add comments on specific lines, and suggest improvements directly in the Pull Request on GitHub.com. As this requires more involved work on GitHUb.com, I added a workflow description that can be accessed here: Pull Requests & Commenting
Resolve Conflicts Locally: Sometimes, you or your student might be working on the same file at the same time, leading to a merge conflict. GitHub Desktop will alert you when this happens. You should always try to resolve these conflicts locally on your computer before attempting to merge.

Proceed with Complete workflow | Return to Section Overview

--- title: "Minimal Setup with Github Desktop" --- **GitHub Account:** \* If you don't have a GitHub account, please create one here: [github.com/join](https://github.com/join) \* **!!** Your username will be visible in your GitHub project (repository) URLs. \* Remember your username and password. **To use Git on your local computer, you need to have Git installed. By installing GitHub Desktop, a Git version gets also installed. Git can also be installed as a standalone version. Here, it's easiest to install GitHub Desktop, and get Git automatically with it. In addition, GitHub Desktop uses an easier authentication than standalone Git versions (but you won't get the full integration in RStudio without installing a standalone version).** (Optional: to check whether Git is already installed, go to [Verify Local Git Installation](verify-git.qmd)) Is **GitHub Desktop** already installed on your computer? **Check by typing 'github' in the Windows search bar.** If installed, **Github Desktop** will show up as a match. ## 1. Installing and Setting Up GitHub Desktop Getting started with **GitHub Desktop** is a straightforward process. 1. **Download the Application:** Go to the official GitHub Desktop website <https://desktop.github.com/download/> and download the installer for your operating system (Windows or macOS). On LJMU managed computers: - Move the downloaded .exe file from 'Downloads' to 'C:\\temp' - Click 'Install anyway' when prompted 2. **Install and Launch:** Run the installer and follow the on-screen prompts. Once installed, the application should launch automatically. If not, start it yourself. 3. **Sign In:** You'll be prompted to **sign in to your GitHub.com account**. Use your GitHub.com credentials. This might be automatically skipped if you are already logged in to GitHub.com. This is a crucial step that connects the application to your online repositories. If you don't have an account, you'll need to create one first on the [GitHub website](https://github.com/), or follow the prompt. ------------------------------------------------------------------------ ## 2. Using GitHub Desktop with a New RStudio Project This is the easiest way to start a new project. You'll create the repository on GitHub and then clone it to your computer. 1. **Create a New Repository:** In GitHub Desktop, click **File \> New Repository...**. 2. **Name Your Project:** Give your new repository a clear and descriptive name (e.g., `my-first-r-project`). Check the box to "Initialize this repository with a README." 3. **Create repository:** Click **Create Repository**. GitHub Desktop will create the local repository in the folder you specified. **!!** To just work locally, with version control, you could stop here. However, to backup your repository remotely, click **Publish repository**. This will publish/push the new repository, i.e. the new folder with all its contents to your GitHub account. 4. **Create RStudio Project:** In RStudio, go to **File \> New Project...**. Select **Existing Directory** and navigate to the folder that GitHub Desktop just created for you. Click **Create Project**. 5. **Initial Commit:** RStudio will now be linked to your Git repository. You'll notice a Git tab in the top-right pane. Back in GitHub Desktop, you'll see that a new `.Rproj` file has been added. Work on your files in RStudio, save them, then switch to GitHub Desktop when you want to commit and push, as follows: - In GitHub Desktop, in the **'Summary' text box** on the left, write a short commit message like "Add RStudio project file" and click **Commit to main**. (It might say 'Commit 2 files to main' if the .gitignore file was added. That's ok!) Note that all changed files have been staged already by GitHub Desktop (i.e. they have a tick mark next to them and are selected). **!!** If you commit here for the first time, you should be asked about the user name and email address to use: - Your Name can be your GitHub user name, but doesn't have to be. This is what appears as the author of your commits on GitHub. - User email has to be an email address connected to your github.com profile. These can be found on github.com, by clicking on your profile picture -\> **Settings** -\> **Emails**. You can use your actual email address, or, more standard, there is a more anonymous email that can be used (look on that page for the email address ending in @users.noreply.github.com). This is the email that will probably be suggested automatically. 6. **Push to GitHub:** Click the **Publish repository** button to upload these changes to your online GitHub repository. Keep all default options. 7. You can now view your linked GitHub repository online. Just click on the **View on GitHub button** in the main GitHub Desktop window. A browser window will open. ------------------------------------------------------------------------ ## 3. Connecting an Existing RStudio Project If you've already started working on a project in RStudio and want to add it to GitHub, here's the workflow. 1. **Add a Local Repository:** In GitHub Desktop, click **File \> Add Local Repository...**. 2. **Navigate to Your Project:** Select the folder that contains your RStudio project. 3. **Publish Your Repository:** Click **Add repository**. An error message will appear, asking you to **create a repository here instead**. Proceed with this option, with the default settings (check the 'initialize with a README' file if you like). Once created and added, you'll see a blue button that says **Publish repository**. Click it. 4. **Name and Publish:** A window will pop up to let you name the new repository on GitHub. Once you've chosen a name, click **Publish Repository**. 5. **Initial Commit:** All of your project's existing files are now ready to be committed in GitHub Desktop. Write an initial commit message like "Initial project files" and click **Commit to main**. 6. **Push to GitHub:** Click the **Push origin** button to upload your project to GitHub. 7. Now, every time you change your code in RSTudio or add a file to your RStudio project, those changes will show up in the GitHub Desktop 'Changes' log on the left. ------------------------------------------------------------------------ ## 4. Recap: Standard Workflow - Commit & Push This is the normal process you'll use with GitHub Desktop. 1. **Make Changes:** Work on your code or documents within RStudio as you normally would. 2. **Open GitHub Desktop:** After saving your files in RStudio, switch to the GitHub Desktop application. 3. **Review and Stage:** GitHub Desktop will automatically show you all the changes you've made. You can review and select the files you want to include in your commit. 4. **Write a Commit Message:** In the bottom-left of the application, write a short, descriptive commit summary. For example, "Add data cleaning script" or "Fix error in ggplot function for Fig 3a". A good commit message explains *what* you changed and *why*. 5. **Commit and Push:** Click the **Commit to main** button. This saves the changes to your local Git history. Then, click **Push origin** to send those changes to your online GitHub repository. ------------------------------------------------------------------------ ## 5. Collaborating with a Student To allow a student to collaborate on your repository, you first need to invite them to the project on GitHub.com. 1. **Invite Collaborator:** On the GitHub website, navigate to your repository (or just click the 'View on GitHub button in GitHub Desktop). Click on the **Settings** tab, then **Collaborators**. From there, you can invite your student using their GitHub username, full name, or email address ('Add people'). 2. **Student Accepts Invitation:** The student will receive an invitation email. They must accept the invitation to gain access. 3. **Student Clones the Repository:** The student should open GitHub Desktop and go to **File \> Clone Repository...**. They will see your project in the list of their repositories and can select it to clone it to their own computer. 4. **Student's Workflow:** The student's workflow is similar to yours, but with one key difference: they should **Pull** before they start working. This ensures they have the latest version of the code. The complete cycle for them is: - **Pull** any new changes from the main repository. - **Make changes** in RStudio. - **Commit** their changes with a descriptive message. - **Push** their committed changes to the main repository. ### From here, go to the [**Complete RStudio/Git workflow**](setup-complete.qmd) or go more in depth below with the current setup. # Optional ## 6. Working with Branches (best practice, but not essential, especially for \<2 users of the same repo) Working directly on the `main` branch can be risky, especially in a collaborative project. A **branch** is a separate version of your project that allows you to work on new features or bug fixes without affecting the main code. A branch is essentially a small, movable pointer to a specific commit. When you create a new branch, you're **not** creating a full copy of your project's files (there's no separate folder for each branch). Instead, you're creating a new pointer that initially points to the same commit as the branch you branched from (e.g., 'main'). - **Commits:** Each commit is a snapshot of your project at a particular point in time. It contains a unique identifier (a hash), metadata (author, date, message), and a pointer to its parent commit. This forms a history of changes. - **Branches:** A branch is simply a name that points to one of these commits. When you switch to a branch, Git updates your working directory to match the state of the files at that commit. When you make a new commit on a branch, Git creates a new commit and then updates the branch pointer to point to this new commit. 1. **Create a New Branch:** In GitHub Desktop, at the top of the application, click on the **Current Branch** dropdown menu and select **New Branch...**. Give your branch a descriptive name (e.g., `add-new-data`, `fix-plot-bug`). 2. **Switch to Your New Branch:** The application will automatically switch you to this new branch. 3. **Make and Commit Changes:** Make all of your changes and commits on this new branch. This keeps them separate from the `main` branch. 4. **Publish the Branch:** The first time you commit to a new branch, you'll need to **Publish branch** to make it available on GitHub.com. 5. **Create a Pull Request:** Once you are done with your work, go to the GitHub website. You will see a prompt to create a **Pull Request**. A Pull Request is a request to merge your changes from your new branch into the `main` branch. This is the perfect time to ask your collaborator for a review or to check for any conflicts before merging. 6. **Merge into Main:** When your work is ready and reviewed, you can merge your branch into `main`. In the Pull Request on GitHub.com, click the **Merge pull request** button. The changes are now safely integrated into your main project. 7. **Clean Up:** Once merged, you can delete your branch from both GitHub.com and GitHub Desktop to keep your project clean. ### 6.1 Collaboration Best Practices on Branches For a smooth collaborative workflow, it's essential that everyone follows a few best practices. 1. **Start with the Latest Code:** Before a student begins any new work, they should always **Fetch origin** and **Pull origin** on their `main` branch to make sure their local version is up-to-date with the shared repository. - **Fetch** just imports all the updated files and the commit history, without **merging** it with any local files. - In contrast, **Pull** is a combination of **Fetch** and **Merge**: It downloads the changes and then attempts to integrate them into your current local branch. 2. **Branch for Every Task:** Encourage your student to create a new, separate branch for *every* new feature, bug fix, or major change they work on. This keeps their changes isolated and makes it easy to review and merge their work without disrupting the rest of the project. 3. **Use Pull Requests for Feedback:** The Pull Request is the central tool for code review. As a tutor, you can review the student's code, add comments on specific lines, and suggest improvements directly in the Pull Request on GitHub.com. As this requires more involved work on GitHUb.com, I added a workflow description that can be accessed here: [Pull Requests & Commenting](pull_comment.qmd) 4. **Resolve Conflicts Locally:** Sometimes, you or your student might be working on the same file at the same time, leading to a merge conflict. GitHub Desktop will alert you when this happens. You should always try to resolve these conflicts locally on your computer before attempting to merge. ### [Proceed with Complete workflow](setup-complete.qmd) \| [Return to Section Overview](/index.qmd)