Using the RPI github
June 2023
John Erickson erickj4@rpi.edu
You've been "voluntold" to use RPI's github for managing your source code; what to do next? This is a concise guide to on-boarding.
Assumptions:
- The reader has a valid RCS id
- A repository already exists on RPI's github instance http://github.rpi.edu ; you've been told to join it!
- You're using a Linux-like operating system (including the command shell on MacOS)
Initializing Your RPI github Account:
Every user with a valid RCS ID can have an account on the RPI github, but the user's account must first be initialized. If you've never logged into http://github.rpi.edu go there now and simply log in with your RCS credentials.
Attempt the github Tutorial:
We strongly recommend users work through the following excellent "Hello World" tutorial before working with real project resources. Substitute the RPI github at http://github.rpi.edu for http://github.com
github "Hello World" tutorial: https://docs.github.com/en/get-started/quickstart/hello-world
On github: Verifying Project Repository Access:
- Obtain the URL for your project's repository. Example: https://github.rpi.edu/RensselaerIDEA/hockey-data
(The above repo is private; users not on the "hockey-data" project cannot access it!) - Log into http://github.rpi.edu and attempt to browse to your project's URL.
- If you are logged in but see a 404 error, your project's repository is private and you have not yet been added as a "collaborator." Contact your project manager and ask them to add you.
On your system: Cloning the Project Repository:
- In the main github page of the repository, click on the green "code" button and copy the URL under the "Clone" section.
- In the shell of your working environment (e.g. the Linux shell on the IDEA Cluster, for example in the Terminal in RStudio Server), change your working directory to your home directory:
cd ~
- Verify your current working directory:
pwd
- In the shell of your working environment (e.g. the Linux shell on the IDEA Cluster, for example in the Terminal in RStudio Server), type the following using that URL
(NOTE: Here we use our hockey example!):
git clone https://github.rpi.edu/RensselaerIDEA/hockey-data.git
- A new directory tree will now be created on your system; the root will be the name of your cloned repository (in our example, "hockey-data")
On your system: "Enter" your Local Repository and Creating a Working Branch
- Enter the directory into which you cloned the project repository. If you followed the instructions above, this will be your home directory
- Change directories into the root level of your cloned repository's directory tree. For our "hockey-data" example, this would look like:
cd hockey-data
- Source code management is all about dealing with different "branches" under development. For our projects this is fairly simple; students are most likely to be contributing independently on their own files, and less often on parts of files with other students.
- Individual developments are managed via named branches. The main branch (formerly called master) is the most advanced version of the repository; think of it as "production." Other named branches are potential contributions under consideration to be merged with and therefore included in the main branch.
- A best practice is to create (or check out) a new branch soon after cloning the project repository, and in general whenever you begin a new coding effort.
- To create a new named branch:
git checkout -b erickj4-13jun
…in which "erickj4-13jun" is the name of our new branch.
- Verify our current working branch:
git branch
…will list the main branch and any other known local branches. In this case an asterisk should be next to your new named branch, which you set as your working branch by checking it out.
- At this point you are ready to create and edit files; git add them to let your branch know to watch for changes; git commit (sort-of like a "save") changes officially to your branch; and git push them to the "remote" repository, known as "origin."
- Then on github you will do a pull request, and your project's merge master will review and execute a merge!
On your system: Adding, Committing, and Pushing Changes
- A git add tells git to watch for changes on specific files. We have found that to avoid conflicts, it is safest to be as specific as possible; if you only edit a single file, only execute git add on that specific file. For example,
git add foo.R
…"adds" foo.R to our current working branch. More than one file can be added, if necessary, but it is best to keep things as simple as possible to avoid errors.
- git commit "saves" the watched changes to the current working branch. It's very important to attach a message to your commit commands; these end up associated with each of the changed (and successfully merged) files in the repository.
git commit -m "My amazing changes"
- After you've edited your file(s), added them, and committed the branch, you are ready to git push your working branch to the remote/"origin." Don't be scared; this does not affect the main branch -- assuming you're not trying to use main as your working branch!
- The syntax of your push explains what does:
git push origin erickj4-13jun
…in which "origin" indicates you are pushing the branch to the github repo the local was cloned from; the branch name (here, "erickj4-13jun") indicates the branch holding the changes you are pushing.
On github: Pull Requests and Merges
- Pull requests are most easily done by browsing to the main page of your repository on the RPI github.
- Assuming you are logged in, you should see a prompt near the top of the repository page inviting you to review the changes for potential conflicts and to submit a pull request.
- Click on the green button; your project's Merge Master will be notified and, if you're lucky, will merge your contributions!
- If you do not immediately see the pull request prompt, you can achieve the same state by selecting your committed branch from the "Branch" drop-down (normally the dropdown defaults to main, or sometimes master).
On your system: Updating your local copy by "pulling" remote changes
- Occasionally you will want to update your local repository with any changes made to main at the origin
- The syntax is to git pull changes to a particular branch at origin into whichever branch you have selected
- You can update either your current working branch, some other working branch, your copy of main, or all of the above.
- Assume we are in erickj4-13jun; the following will update all of the files in that branch to their state in the main branch in our origin repository:
git pull origin main
- If we have made any changes to the files that are designated to be updated, git will notify us of a conflict and refuse to merge the changes. The solution is usually to git stash our changes, re-attempt the git pull and implement the changes after the successful pull.
References