watonomous.github.io

1. Knowledge Base
2. Knowledge Base Home
3. General Tutorials

[ Knowledge Base : Git and Gitlab Tutorial ]

Created by [ Rowan Dempster], last modified by [ Henry Wang] on Jan 08, 2020

Introduction

The purpose of this tutorial is to get new WATonomous members familiar with our project on uWaterloo's GitLab. This tutorial mostly comprises of the popular commands used in Git and how it is used in WATO. This guide provides information for setting up the WATonomous git repo, rules about using git, useful git commands, as well as good practices and guidelines when working with git.

We are using the GitFlow workflow. Please become familiar with this workflow. Learn about it here: https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow.

[In addition to the Gitlab notes below, here's the official starter guide from Gitlab: ]https://docs.gitlab.com/ee/gitlab-basics/

WATO uses Git under uWaterloo's organization, which can be found at https://git.uwaterloo.ca/WATonomous

Depending on which team you're in, your manager (or team lead) may have already set up the project for you. In order to contribute to the project, make sure you're given developer access to it by going under Settings → Members and looking for your name.

• Introduction
  • Setup
    • Installing Git
    • Accessing GitLab
    • Setting up SSH keys
    • Understanding Repo Structure
    • Setting up Local Workspace
  • Using Git
    • Starting a Task
    • Committing Changes
    • Merging Your Branch
    • Merge Method
  • Useful Git Commands
  • Useful Git Resources

Setup

Installing Git

If you do not already have git installed through your terminal, follow the below link: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

• On a Debian-based machine: sudo apt-get install git
• For Mac/Windows, download the installer from the link above and follow the instructions

Accessing GitLab

WATonomous has a private repo through the university’s GitLab tool. General sign-in link can be found here: https://git.uwaterloo.ca/users/sign_in

• If you have never enabled your GitLab account, you need to first enable your Quest account to be active on GitLab
• Log in with your Quest credentials

Setting up SSH keys

Before you can access any repositories from your local machine, you will need to upload an SSH key to your GitLab profile.

• Follow these instructions to generate an SSH key: https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key
• To upload they key to GitLab, go to Profile Settings > SSH Keys, and paste your SSH key into the key field and submit.

Understanding Repo Structure

The WATonomous Repo is setup such that each subteam (e.g. Prediction, Decision, …) has its own repo.

• Each main repo contains 2 branches by default: master and develop

• The main repo is used for code
  • Never push directly to develop or master branch
  • All code need to be merged via merge requests that are approved by a subteam lead or project manager

Setting up Local Workspace

Now you will set up a WATO workspace on your local computer to hold all the repositories. Create a WATO folder on your computer and open up a command terminal. Enter the following into the command line:
cd <path-to-wato-folder>
git init
git clone gitlab@git.uwaterloo.ca:WATonomous/<name-of-repository>.git
cd <name-of-repository>
git checkout develop
This will create a local copy of the repository. You should now see a folder named <name-of-repository> in the WATO folder you created.

Now you are ready to get started!

Using Git

Starting a Task

Normally, any task you are working on will have a corresponding Jira task.

• When working on a task, branch off of develop of the appropriate repository and name the branch using the following form:
  • For a feature: feature/<jiraID>-<veryBriefSummaryOfTicket>
  • For a bug: bugfix/<jiraID>-<veryBriefSummaryOfTicket>
  • Use the command below to create the branch and automatically checkout to the new branch created: git checkout -b <branch-name>
• Use the command git status to check the status of your current local workspace and display the current branch.

Committing Changes

When you are working on your own branch, you may want to occasionally back up your work on the server. The following commands can be used for pushing code to a remote branch.

• Use git add to stage files. Or use git rm if deleting files.
• After staging local changes, commit them using: git commit.
• The convention to writing commit messages is summarized below and fully justified at https://chris.beams.io/posts/git-commit/.
  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how
• Push local commit to remote branch using: git push origin <branch-name>

Merging Your Branch

Once you have fully tested the code on your branch and are ready to merge the code into the develop branch. Keep in mind that most people do not have push permission for develop and master branches. Follow the below steps to get your code merged.

• Before merging your branch to develop, make a pull request and add the subteam lead as a reviewer.
• The pull request can be done by copying the URL from the message in the terminal when you push your changes on your local branch
• In GitLab, this is sometimes referred to as the “Merge Request”
  • More information about Merge Requests here: https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html
• By opening the URL you obtained after pushing your commit, make sure the source and destination branches are selected as source being <your-branch> and destination being develop.
• Select the members that you would like to do your code review
• During code review, your reviewers may make comments/suggestions for changes
  • If this is the case, make the desired changes on your branch and push again, the new diff of the files will appear in your merge request
• Once all issues from your merge request are resolved, get your subteam lead to "merge" your code into the develop branch.

Merge Method

It's generally bad practice to git merge branches into each other because doing so creates merge commits and creates a non-linear history. Git Lab repos have settings to configure to merge method. By default the merge method is "Merge commit". It'd suggest setting it to "Fast-forward merges only". Or manually rebasing and having the repo maintainers push to the remote branch.

Useful Git Commands

git pull <branch-name>

• Updates your local workspace with the most-recent changes in the repo of the selected branch; branch parameter is optional git checkout <branch-name>
• Switches your current active branch to the <branch-name> branch git status
• Check the current status of your local repo git log
• Shows commit history of your current branch git diff
• Shows changes of your local repo and the HEAD of the branch git reset --hard
• Resets your local workspace to the HEAD of branch and discards all uncommitted changes git stash
• Temporarily saves your changes and brings your local workspace to HEAD of branch; you can retrieve your changes by using git stash pop git revert <commit-hash>
• Reverses the git commit git merge --abort
• Undo a merge

Use .gitignore file to keep the repo clean by not tracking any files with extensions listed in the .gitignore file (e.g. binary files, IDE-specific project files…)

Useful Git Resources

Git workflow: https://www.atlassian.com/git/tutorials/comparing-workflows#gitflow-workflow

Thorough git tutorials: https://www.atlassian.com/git/tutorials

Git documentations: https://git-scm.com/docs/gittutorial

\

Document generated by Confluence on Nov 19, 2021 12:20

Atlassian