1 Git
Git is a free and open-source version control system. When used regularly and as intended, developers will have a full history of their project within a local repository. In addition to a historical log of changes to project files, git allows for project branching to support users to test/develop new code, while maintaining the master version for easy reversion. When users are ready to implement their new branch into the main codebase git can be used for merging files, whereby it tracks changes and ensures there are no conflicts between the main version and the new version.
Beyond local usage, git is also supported by web-based repositories such as Github and Gitlab, where projects can be pushed, pulled, and cloned. These sites allow for easy collaboration with other developers and provide a number of user-friendly features that make working with git easier.
NOTE
In RStudio, git is accessed in the terminal or in the top right under the Git tab when Git has been initialized for the project.
1.1 Basic git workflow
Step 1) Create a project.
Step 2) Initialize git.
git init
Step 3) Check your project file status
git status
Step 4) Add a file to the local repo
git add filename.R
Step 5) Commit your change with a message
git commit -m "Add filename.R"
Step 6) Create a branch to test/develop code
git branch test_branch
Step 7) Go into that branch
git checkout test_branch
Step 8) Modify your code and repeat steps 3 and 4
Step 9) When ready merge branches
git merge master test_branch
TIP
Branching is useful when you have a stable codebase that you do not want to break or if you are working collaboratively on a code base. You can create a branch to do development work and test new features until it’s ready for integration with the stable codebase or your coworkers. If you are developing something from scratch by yourself you may not need to use branching until later.
1.2 Setting up Github or Gitlab projects
Ensure your profile is set up
git config --global user.name "Braeden Klaver"
git config --global user.email "braeden.klaver@bccdc.ca"
WARNING
When you create a new repository on github or gitlab it can cause issues if you create it with a README. It is recommended when creating new repositories to make sure they are a clean slate.
1.2.1 Pre-existing project on Github or Gitlab
Step 1) In your terminal navigate to the folder you want to clone the project to
cd "U:/myprojects"
Step 2) Clone the project into that folder and give the project a name
git clone http://lvmgenodh01.phsabc.ehcnet.ca/braeden.klaver/test.git myproject
1.2.2 Personal project without git
Step 1) Open your R project
Step 2) Initialize git
git init
Step 3) Create a project on Gitlab or Github
Step 4) Connect your R project to that repository (should be the URL)
git remote add origin http://lvmgenodh01.phsabc.ehcnet.ca/braeden.klaver/test.git
Step 5) Add and commit your files
git add .
git commit -m "Initial commit"
Step 6) Push your project to that repository
git push -u origin --all
1.3 Collaborative git workflow
In addition to the basic workflow, when working with a web-based repository like Github or Gitlab there are additional steps you will need to take:
Step 1) Pulling changes from the repository - your coworkers may have made changes!
git pull
Step 2) Follow the basic workflow (Section 1.1)
Step 3) Pushing your changes to the repository - your coworkers will want to be up to date!
git push or git push origin
NOTE
You have to use git push origin branch_name when working on a branch that isn’t your main or master.
1.4 Using Git at the BCCDC
1.4.1 Git on Citrix
Git is installed on citrix already, it can be initialized as described above or you can click a check box to create a git repository when creating a new project.
TIP
If you have a local R installation and you’d like to work there but do not have git installed locally you can still leverage citrix R to use git for your projects.
1.4.2 Git locally
If you want to use Git locally you will need to install it for your system. Typically, this will be the 64-bit windows version found here. Once it is downloaded you should be able to use git as described above in your local RStudio.
NOTE
The benefits of having a local installation of git is that if you primarily use your local RStudio you can access it directly through there rather than jumping to citrix. Additionally, you can use it to connect to repositories in Github, which is not possible on citrix.
1.4.3 Github
Because Github is an external web-based repository there are some considerations for its use at the BCCDC. Currently, there are no formal guidelines on using it, for this reason using it for BCCDC-specific projects should be avoided.
1.4.4 Gitlab
The BCCDC has a private Gitlab repository, which can be used for regular BCCDC projects within the scope set out in the guiding document.
NOTE
You can request access to Gitlab via this form.
1.4.5 Suggested project workflow
Working with git tracked projects requires you to have your own local repository. For this reason, it is recommended to keep this repository in your U:/ drive. In addition, we would recommend having another local repository in the O:/ drive, which would be dedicated to running pipelines or deploying apps and not for development work.
WARNING
Some project data may not be permitted on your U:/ drive, therefore ensure your code is loading that data from an appropriate location.
1.5 Basic Git Commands Summary
| Command | Description |
|---|---|
| git init | Initialize git for the directory |
| git status | Check the status of files in the directory (eg. are they being tracked, have they been modified) |
| git add | Stage a file for commit |
| git rm | Remove a file staged for commit |
| git commit | Commit your changes |
| git branch | Create a branch for development work |
| git checkout | Checkout a branch to work within |
| git merge | Merge two branches together |
| git pull | Pull the most up-to-date repository from a remote (ie. Github or Gitlab) |
| git push | Push your changes to a remote repository (ie. Github or Gitlab) |
NOTE
There are many other functions that you can use in git beyond those listed above, however, these give you the tools to get started.