Skip to main content

WEEL Guide

23 Git

23.1 Slides

Workshop: Git and Projects

Date: February 6 2020

Slides and Resources

23.3 Use SSH

Recently, GitHub deprecated basic passwords for authentication so my recommendation is to use SSH throughout. See Happy Git With R’s SSH keys introduction. Then when you grab links to clone, eg. the WEEL’s ewc project, use the format git@gitlab.com:WEEL_grp/ewc.git and not https://gitlab.com/WEEL_grp/ewc.git

23.4 .gitignore

23.4.1 Include one file in an ignored folder

Use a wildcard * to exclude everything in a folder and include the file with !. The wildcard should be specified exactly on the folder, not the larger directory. In the example below, we ignore everything in the data/derived-data folder, not just the data/ folder.

Eg. in file .gitignore:

.Rproj.user
.Rhistory
.RData
.Ruserdata

data/raw-data/
data/derived-data/*
!/data/derived-data/output.Rds

23.5 Tags

We can add git tags to our commits, to keep track of specific versions or steps of a repository.

For example, spatsoc and other packages use git tags to mark specific versions of the package. These versions link to GitHub/GitLab releases, making it easy to install specific versions.

For papers, you can track different stages of revisions:

To add a tag in GitAhead, just right click on the commit, add tag, then fill in the name (no spaces) and check “push to origin”. Then you will be able to find the tags on gitlab for example: wildcam tags.

23.6 Blame and history

Git Blame and Git History can be used to get information about when files were changed and by who.

For example: head over to GitLab.com and browse to one of your files. Open it up and select “history”. You will all the times the file was changed, and selecting any of the commits will show you what it looked like at that point.

Alternatively, you can use select “blame” to show who changed each line in a file and at which commit.

23.7 Issues

Issues are a tool available on GitLab and GitHub for collaborating on projects, getting help and tracking decisions. They are used extensively in the FOSS world and are often the way R package developers opt to receive bug reports and feature requests from their users.

Issues can be used for both personal and group projects. Some uses include:

  • collaborating
  • developing methods
  • troubleshooting code
  • tracking decisions or assumptions
  • defining thresholds, variables
  • reporting bugs
  • requesting new features

Issues have a number of advantages over private email, in-person conversations or TODO, NOTE and other comments embedded in code because they:

  • are easily searched
  • can be grouped or categorized using labels
  • can be assigned to individuals, groups or teams
  • keep everyone in the loop
  • are a resource for future users (including yourself!)
  • allow for asynchronous communication
  • keep track of the history of decisions, progress, etc.

23.7.1 Example issues

23.7.1.1 Bug or troubleshooting

I’m trying to do this and it isn’t working

# Some concise title
(One/two sentence description summarizing issue. )

## Steps to reproduce
(How one can reproduce the issue)
1.
2.
3.

## Observed behaviour

## Expected behaviour

## Sample of output tables, screenshots

## Possible fixes

## Session info
(if R related, paste the results of sessionInfo())

23.7.1.2 Method development

I’d like to try and do this

# Some concise title
(One/two sentence description summarizing the objective. )

## Description
(Include goals, use cases, benefits)

## Progress
(Where did you get?)

## Next steps
(How do you think we could solve it? Who can you assign
  this issue to? Who can you mention to get their input?)

And once solved, post the code that actually solved it. This is one of the main ways that Issues can be useful to future users.

23.8 Tracking different file types

Git won’t be able to track changes in all data (eg. .Rds and other binary file types) and output R Markdown file types.

For R Markdown, use simply:

output:github_document

or keep the .md file along with your main output type. Either by rendering multiple output formats or using:

output:
  pdf_document:
    keep_md:true
output:
  html_document:
    keep_md:true

Generate figures as seperate PNGs and include them in the document using knitr::include_graphics(). This way, the PNGs can be diffed by Git and easily viewed separate from the R Markdown output.

23.9 GitLab CI/DI and GitHub Pages

23.9.1 Testing data

Using tests is a great way to clarify your expectations about data outputs, that be checked whenever code is updated. Check out the testthat package and checkr package.

23.10 Moving from GitLab to GitHub

Four options and it depends on if you’d like your repository to be mirrored over (dynamic, with updates) or imported (static, one time snapshot). Using the GitHub Importer (option 4) is easy but will only take a static snapshot. Otherwise, adding multiple remotes (option 1), changing your remote (option 2), or using an access token (option 3) will all copy over future changes.

23.10.1 Option 1: Adding multiple remotes (dynamic)

If we want multiple Git repositories to be updated whenever we push, we can set multiple remote repositories.

git remote set-url origin --push --add <a remote>
git remote set-url origin --push --add <another remote>

Like the option below, this needs to be set for all users that want to push to both remote repositories.

23.10.2 Option 2: Changing your remote (dynamic)

Note: This approach locally changes your remote path to the Git repository. If there are multiple users of the repository, they must either 1) also change their remote path or 2) clone the new repository at the updated path ( and ideally delete the old local repository).

On GitHub.com:

  1. Make an empty repo (https://github.com/new). Don’t select “initialize with a README” - you want an empty repository.

In GitAhead, or other Git tool on your computer:

  1. Open the repository you want to move to GitHub.

  2. Edit the URL of the remote. In GitAhead: Select the “Remote” menu/Select “Configure remotes”/Double click on the URL and change the value to your GitHub clone URL eg. https://github.com/wildlifeevoeco/MovingAcrossGradients.git or :wildlifeevoeco/MovingAcrossGradients.git

  3. Push. It may take longer than usual, it is going to push the entire Git history to the empty GitHub repository.

  4. Check your new GitHub repository. You should see all the commits and files there.

If you want your GitLab version to stay up to date, use a Pull remote mirroring. More information here: https://docs.gitlab.com/ee/user/project/repository/mirror/pull.html

23.10.3 Option 3: Using an access token (dynamic)

On GitHub.com:

  1. Make an empty repo to receive commits from GitLab (https://github.com/new). Don’t select “initialize with a README” - you want an empty repository.

  2. Generate a new personal access token at https://github.com/settings/tokens

    • Select public_repo

  3. Copy it, to use as password on Gitlab.com below

On GitLab.com:

  1. Navigate to “Settings/Repository” (https://gitlab.com/user/repository/-/settings/repository)
  2. Select “Mirror a repository”
  3. Mirror direction: Push
  4. Repository URL: https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git
  5. Password: paste the personal access token generated on Github here

Check results:

  1. Wait for the spinning circle to finish, make sure no errors come up.
  2. Navigate to your new GitHub repository. It may take a few minutes to update.

23.10.4 Option 4: Using GitHub Importer (static)

  1. Open https://github.com/new/import.
  2. Select the “Owner”. Note: you can select the wildlifeevoeco as “Owner” if this is a lab paper/project. If you don’t see that as an option, ask Alec to add you as a member of that group.
  3. Provide a repository name.
  4. Select “Public”.
  5. Select “Begin import”
  6. If prompted for credentials, provide them for the repository that is being imported, not GitHub.
  7. Check your email for confirmation.

The GitHub Importer is described here.