Thus far your repositories have all been in your local filespace. This is often on a laptop, although for consistency this semester as we learn, we have been creating and using repos on Edupod Rstudio.
Even when working on one’s own (solo), it can be convenient to have a backup in the cloud. Git hosting services provide this. Examples include Github, GitLab, and BitBucket. As we will see later, these services also provide a platform for collaborating with others, but they work just as well as a backup for solo work.
You will need to have a working GitHub account. You are welcome to use an existing Github account (if you happen to have one), or you can create one just for this course (a “throwaway”) or you can use your real name and plan to retain this account for your professional life. Whichever you choose you will need a working email address associated with the account (to confirm and see the notifications).
Once you are logged into GitHub you can create a repository using the “New Repository” button (which is usually green colored).
You will need to give two things:
A repository name. I suggest that you use a prefix of i320d- for all the repos used in this class. That will ensure you can easily clean them up later.
Be sure to select “Add a README file” under the Initialize this repository with … section.
Once you’ve created the repository you will see a “Quick Setup” page. This shows you the URL of the repository that you’ve created. This is how mine looks:
You should copy the URL using the little grey box-on-box on the right.
Now that we have an empty repo on Github, we can bring it down to our local space. This uses a git command called git clone.
Go to the Edupod Rstudio and to the Terminal tab.
Before running git clone, everyone needs to ensure they are in a folder that is not inside another repo. You can place repos anywhere you want. I suggest placing them all into your home folder on edupod. You can be sure you are there by running this command (read as “cd tilde” because tilde is a shortcut for your home directory).
cd ~To be sure that you aren’t inside another repo you can run git status and you want to see a fatal error.
git status
fatal: not a git repository (or any parent up to mount point /stor/home)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).If you do not see the fatal error, then you need to move up in your folder hierarchy until you are not in a repo. Use cd .. or cd ~. If you still get that error and you are in your home folder, see FAQ for “I accidentally made my home folder a git repo” at Section A.2
Then clone your repository and change directory into it.
For my example repo in the image above this would be:
git clone https://github.com/jameshowison/i320d-test1.git
cd i320d-test1You will need to replace the repo URL and the repository name to match yours like:
git clone <repo_url>
cd <repository_name>Now we can do our usual git stuff: We can edit a file, save it, then use git add and git commit -m "Some message" to store our new version in git.
As usual, here is a command that simulates editing and saving a file (which you can also do through the RStudio interface):
echo -e "\n\nA new line in README" >> README.md
git add README.md
git commit -m "Added line to README"Your password for GitHub will give you access to the GitHub web interface, but to connect git on the commandline to GitHub we need a Personal Access Token (PAT). You can think of this as a special use password. Go to https://github.com/settings/tokens
You will then be able to copy the PAT. You need to keep this somewhere you can copy from in class. I put it into my password manager (I use 1password). Note that this gives full access to your GitHub account, so if you have work stuff or other things in there, come talk to me or use a “fine-grained access token” scoped only to the repos for this class.
The git push command will move any new work from your local repo, up to GitHub.
git pushRstudio on EduPod will pop up a window for your username/password. You should use your GitHub username, but the PAT when asked for the password. Your regular GitHub password will not work. You have to use the PAT you created in the previous step. If you didn’t copy it down, you can create a new one, don’t forget to store it somewhere so that you can copy it for use in class.
By default you will have to re-enter this username/PAT any time you haven’t run a git push command for 15 minutes. More details in the FAQ on this in Section A.1.2 but you can reduce pops by running:
git config --global credential.helper 'cache --timeout=10000000'You may also see a message about needing to set an upstream branch. Something like this:
$ git push
fatal: The current branch test-branch has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin test-branchYou can copy that suggested command within terminal as run it. This tells git to create your new branch on the origin remote.
On GitHub you can now find your branch using the Branch drop-down.
Select that and you will see a “Compare & pull request button”
When you click the green button you will see:
Notice the purple circle that shows base: main <-- compare: new-feature. Notice that the arrow points right to left. The destination of the PR comes first (here it is main) and the place we are merging from comes second (here it is new-feature).
The interface shows that the branches can be merged automatically. This means that the changes in the new-feature branch would not cause conflicts if merged into main.
You can go ahead and Create the PR.
This will lead to a PR page, where you could chat about the suggested changes.
Notice the sentence in the purple circle: jameshowison wants to merge 1 commit into main from new-feature that is a useful succient summary of what a PR is: it is a request to merge a set of commits from one branch into another.
If you hit the “Merge Pull Request” button GitHub will merge the branch to main, close the PR, and suggest that you delete the branch.
All the PR steps have happened on GitHub only, so they aren’t yet reflected in your local repo. We have merged new-feature to main on GitHub.
At this point you need to synchronize by first switching to main:
git checkout mainand then get changes from the remote
git pull
sequenceDiagram
participant GitHub_main AS GitHub main
participant local
participant local_new AS local new-feature
participant GitHub_new AS GitHub new-feature
GitHub_main ->>local : git clone
local ->> local_new : git checkout -b new-feature
local_new ->> local_new : edit/add/commit
local_new ->> GitHub_new : git push
GitHub_new ->> GitHub_main : Create/Merge Pull Request
GitHub_main ->> local : git checkout main / git pull