Setting up & using git

This session will cover:

Setting up git on computer
- Installing git
- Setting up your identity
git basic workflow using RStudio
- Cloning a Repository from GitHub to your computer using RStudio projects
- Tracking changes to your scripts
- Pushing your changes to GitHub

Setting up git on your computer

MacOSX and Linux computers all come with git pre-installed, but it is not always directly usable. The best way to test if git is ready to use is at the command line:

git --version
# git version 2.39.3

It should return something like above. If you get an error, you will have to install git

Installing git

You can download a copy of git here: https://git-scm.com/downloads and follow the instructions according to your Operating System.

Windows

You can keep the options to default during the installation, until you reach Configuring the terminal emulator to use with Git Bash -> be sure Use MinTTY is selected. This will install both git and a set of useful command-line tools using a trimmed down Bash shell.

Mac OSX

Depending on the version, you might have to run a few commands from the terminal. Please refer to the README.txt that comes with the download regarding the exact steps to follow.

Setting up your `git` identity

Before you start using git on any computer, you will have to set your identity on your system, as every snapshot of files is associated with the user who implemented the modifications to the file(s).

Open the Terminal or git bash and then type the following commands.

Setup your profile

At the commande line

If you are not sure if you have already set your git identity you can check this running this command:

git config --global --list

If you identity is not set yet, you need to provide your name and email (we recommend to use the same email as used when setting your GitHub account):

git config --global user.name "your Full Name"
git config --global user.email "your Email"

Optional

Check that everything is correct:

git config --global --list

Modify everything at the same time:

git config --global --edit

Set your text editor:

git config --system core.editor nano

Here nano is used as example; you can choose most of the text editor you might have installed on your computer (atom, sublime, notepad++ …).

Problem with any of those steps? Check out Jenny Brian Happy git trouble shooting section

Using Git

Clone a repository

Tip

If you not have yet your favorite-desserts GitHub repository, please follow those steps

Navigate to the folder (e.g cd ~/Documents) where you want to save your repository and run the following command:

git clone https://github.com/brunj7/favorite-desserts.git

You should have a new folder on your local machine named favorite-desserts after your repository :

ls

Go inside the repository:

cd favorite-desserts
ls -al

This should return the exact same content that is currently on GitHub!

Tracking your work

Let’s create a text file called index.md and add it to our repository. The file will later be converted into a webpage by GitHub pages. We’ll write the file using a syntax called Markdown, which is why we use the .md extensions.

Type the text below, replacing the names with people you know:

## Listing of my favorite desserts

- Julien, crepes

Exit nano and save your changes.

Check it worked:

$ cat index.md

You should see the content you just typed!

If we check the status of our project again, Git tells us that it’s noticed the new file:

$ git status

On branch main

No commits yet

Untracked files:
   (use "git add <file>..." to include in what will be committed)

    index.md

nothing added to commit but untracked files present (use "git add" to track)

The “untracked files” message means that there’s a file in the directory that Git isn’t keeping track of. We can tell Git to track a file using git add:

$ git add index.md

and then check that the right thing happened:

$ git status

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

    new file:   index.md

Git now knows that it’s supposed to keep track of index.md, but it hasn’t recorded these changes as a commit yet. To get it to do that, we need to run one more command:

$ git commit -m "start new webpage"

[main (root-commit) f22b25e] Start new webpage
 1 file changed, 1 insertion(+)
 create mode 100644 index.md

When we run git commit, Git takes everything we have told it to save by using git add and stores a copy permanently inside the special .git directory. This permanent copy is called a commit (revision) and its short identifier is f22b25e. Your commit may have another identifier.

We use the -m flag (for “message”) to record a short, descriptive, and specific comment that will help us remember later on what we did and why. If we just run git commit without the -m option, Git will launch nano (or whatever other editor we configured as core.editor) so that we can write a longer message.

Good commit messages start with a brief (<50 characters) statement about the changes made in the commit. Generally, the message should complete the sentence “If applied, this commit will” . If you want to go into more detail, add a blank line between the summary line and your additional notes. Use this additional space to explain why you made changes and/or what their impact will be.

If we run git status now:

$ git status

On branch main
nothing to commit, working tree clean

it tells us everything is up to date. If we want to know what we’ve done recently, we can ask Git to show us the project’s history using git log:

$ git log

commit f22b25e3233b4645dabd0d81e651fe074bd8e73b
Author: ...
Date:   Thu Aug 22 09:51:46 2013 -0400

    start new webpage

git log lists all commits made to a repository in reverse chronological order. The listing for each commit includes the commit’s full identifier (which starts with the same characters as the short identifier printed by the git commit command earlier), the commit’s author, when it was created, and the log message Git was given when the commit was created.

Where Are My Changes?

If we run ls at this point, we will still see just one file called index.md. That’s because Git saves information about files’ history in the special .git directory mentioned earlier so that our filesystem doesn’t become cluttered (and so that we can’t accidentally edit or delete an old version).

Let’s adds more information to the file. (Again, we’ll edit with nano and then cat the file to show its contents; you may use a different editor, and don’t need to cat.)

$ nano index.md

## Listing of my favorite desserts

- Julien, crepes
- Sophia, chocolate

When we run git status now, it tells us that a file it already knows about has been modified:

$ git status

On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   index.md

no changes added to commit (use "git add" and/or "git commit -a")

The last line is the key phrase: “no changes added to commit”.

We have changed this file, but we haven’t told Git we will want to save those changes (which we do with git add) nor have we saved them (which we do with git commit). So let’s do that now. It is good practice to always review our changes before saving them. We do this using git diff.

This shows us the differences between the current state of the file and the most recently saved version:

$ git diff

diff --git a/index.md b/index.md
index 7d781a7..bbb33fe 100644
--- a/index.md
+++ b/index.md
@@ -1 +1,3 @@
## Listing of my favorite desserts

- Julien, crepes
+ - Sophia, chocolate

The output is cryptic because it is actually a series of commands for tools like editors and patch telling them how to reconstruct one file given the other. If we break it down into pieces:

The first line tells us that Git is producing output similar to the Unix diff command comparing the old and new versions of the file.
The second line tells exactly which versions of the file Git is comparing; 7d781a7 and bbb33fe are unique computer-generated labels for those versions.
The third and fourth lines once again show the name of the file being changed.
The remaining lines are the most interesting, they show us the actual differences and the lines on which they occur. In particular, the + marker in the first column shows where we added a line.

After reviewing our change, it’s time to commit it:

$ git commit -m "add Sophia"

On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   index.md

no changes added to commit (use "git add" and/or "git commit -a")

Whoops: Git won’t commit because we didn’t use git add first. Let’s fix that:

$ git add index.md
$ git commit -m "add Sophia"

[main 019f377] add Sophia
 1 file changed, 1 insertions(+)

Note

Git insists that we add files to the set we want to commit before actually committing anything. This allows us to commit our changes in stages and capture changes in logical portions rather than only large batches. For example, suppose we’re adding a few citations to relevant research to our thesis. We might want to commit those additions, and the corresponding bibliography entries, but not commit some of our work drafting the conclusion (which we haven’t finished yet).

To allow for this, Git has a special staging area where it keeps track of things that have been added to the current changeset but not yet committed.

Exploring git history

You can look at the history of what we’ve done so far:

$ git log

It should look something like this:

commit d11d7e52ab98d3d4c18cde4c4a0bbeea3fe40983 (HEAD -> main)
Author: ...
Date:   Thu Oct 19 12:07:51 2023 -0400

    add Sophia

commit 019f37773f9f18b77f508990df65e56a34df45de
Author: ...
Date:   Thu Oct 19 12:03:04 2023 -0400

    start new webpage

commit 8defaab26aa641a4233896ec68e603c541aa77b4
Author: ...
Date:   Thu Oct 19 12:01:17 2023 -0400

    intial commit

Paging the Log

When the output of git log is too long to fit in your screen, git uses a program to split it into pages of the size of your screen. When this “pager” is called, you will notice that the last line in your screen is a :, instead of your usual prompt.

To get out of the pager, press Q.
To move to the next page, press Spacebar.
To search for some_word in all pages, press / and type some_word. Navigate through matches pressing N.

To avoid having git log cover your entire terminal screen, you can limit the number of commits that Git lists by using -N, where N is the number of commits that you want to view. For example, if you only want information from the last commit you can use:

$ git log -1

commit d11d7e52ab98d3d4c18cde4c4a0bbeea3fe40983 (HEAD -> main)
Author: ...
Date:   Thu Oct 19 12:07:51 2023 -0400

    add Sophia

You can also reduce the quantity of information using the --oneline option:

$ git log --oneline

d11d7e5 (HEAD -> main) add Sophia
019f377 start new webpage
8defaab initial commit

You can also combine the --oneline option with others. One useful combination adds --graph to display the commit history as a text-based graph and to indicate which commits are associated with the current HEAD, the current branch main, or [other Git references][git-references]:

$ git log --oneline --graph

* d11d7e5 (HEAD -> main) add Sophia
* 019f377 start new webpage
* 8defaab initial commit

Setting up git on your computer

Installing git

Windows

Mac OSX

Setting up your git identity

Setup your profile

At the commande line

Optional

Using Git

Clone a repository

Tracking your work

Exploring git history

Paging the Log

Setting up your `git` identity