Git Control

A quick summary of using Git

Initial Setup

  1. Create a GitHub Account and log in.

  2. If you do not have access to the UAS drone code repository already, mssage in Slack Comran or in the #newbies channel your GitHub username in order to be added onto the SUAS repository. If you do not have access to the SUAS repository, the rest of the procedure below will not work.

  3. Install the 'Git' package if your machine does not already have it.

    sudo apt-get install git
    
  4. Add an SSH-Key onto your local machine or VM. We recommend NOT entering a passphrase.

  5. Clone the repository - assure you are cloning with an SSH key.

    git clone --recursive git@github.com:uas-at-ucla/drone_code.git
    cd drone_code
    

Branching

Branching is a system we use so that we can constantly develop our code in increments. After you successfully clone the repository, do not edit the files directly. You need to create your own branch off of MASTER.

The MASTER branch is the final product we release to for our drone. Everyone on the team will have their own branch to work on - you can think of the branch as your own sandbox. You will submit your code through a 'Pull Request', in which the respective leadership committee will review the code for approval and merging. The purpose of this is to make sure your code does not break anything severe on the master branch.

Creating Your Own Branch

  1. Create the remote branch. In the UAS Repository, by the left-side section you should see a box that says 'Branch: master'. Click on it, and create the remote branch. Name the branch by the corresponding GitHub issue. The remote branch is the cloud where you store your newly edited files and allow everyone else to see your edits.

  2. In the drone_code directory, run the following:

    git fetch
    git checkout -b GITHUB-ISSUE origin/GITHUB-ISSUE
    

Pulling, Pushing, and Merge Conflicts

  1. After you make some edits, you can check the difference between your code and the GitHub repository.

    git status
    git diff
    
  2. It is good practice to develop your code incrementally and back-up your edits onto GitHub - it is very common for people to accidentally lose all their data.

    git add FILE_NAME
    git commit -m "Enter commit message"
    git push
    
  3. If you work on two separate machines or want to obtain the latest MASTER updates, you can simply pull all the content from the GitHub repository.

    git checkout master
    git pull
    git checkout GITHUB-ISSUE
    git merge master
    
  4. If a merge conflict exists, a 'MERGE CONFLICT' message will appear immediately after the merge. Simply edit the files and fix them. If you are unsure what to delete or fix, ask others for help.

Pull Request Process

Pull requests are what you submit for people to review your code. Reviewers will see the latest file edits you made that do not exist in the MASTER branch.

  1. Go to the UAS Repository.

  2. Near the top section, you should see a series of tabs: Code, Issues, Pull Requests, Projects, Wiki, Insights. Click on the 'Pull Requests' tab.

  3. On the right-side, click on 'New Pull Request'.

  4. Choose your branch. Check the diffs to make sure the branch contains the changes you want. Do not push any more changes until the PR has been approved.

  5. After the PR has been approved, pull from MASTER and compile.

    git checkout master
    git pull
    
  6. Do not delete your branch after a successful merge. The reason being is for convenience. It is easier for you to constantly merge the master branch into your own branch. See step 3.

And that's all the commonly used git controls. There are other useful commands you can google if you ever run into special situations. If you are new or not well-familiar with git, you will grow use to it after consecutive use and it will become almost second nature to you.

Using a Graphical Interface for Git

Using git with a graphical interface can help your workflow by giving you a more visual representation of the repository. VS Code has good git integration, and there is a plugin available for enhancing this functionality. Another option is GitKraken, which is a robust desktop app for git.