ElectroHolography Laboratory

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Git Usage=====
-----
====Basics====
Some terms that you'll need to understand in context (several of these are commands for the git CLI tool):

  * **Git:** A popular Version Control System
  * **Repository:** A storage location for a single project
  * **Push:** Update the remote repository with 
  * **Pull:** Load new changes and branches from a remote repository (or another branch)
  * **Add:** log new/changed files to be "commit"ed
  * **Commit:** Lock in a set of changes to the files. These can be rolled back ("revert"ed), or new branches can be made from previous commits if something goes wrong. Each commit must have a "message", or title of some sort to explain what this commit does.
  * **Branch/Fork:** An alternate development path. Think of it as a sub-project within the main project. For example, a project for developing Unix would need a BSD branch. Every project will have at least one branch called "master". Normally, etiquette would state that you only make significant changes in a separate fork and merge them later. Forks can, in turn, have sub-forks (in the Unix example, think of NetBSD and OpenBSD as forks of BSD, which is in turn a fork of Unix).
  * **Merge:** Combining two branches (especially merging a forked branch back into its parent)
  * **Clone:** Copy a remote repository to your local machine. This let's you work on a local copy of the repository then "push" your changes.
  * **Checkout:** Switch to a different branch in the same project. Can also be used to restore the tree structure (by checking out a parent branch)
    * :!:**WARNING**:!: - if you checkout a branch or commit when there are uncommitted changes in your local copy, you'll lose them (they'll be overwritten). Additionally, if you checkout something else after committing but haven't synced it to the server, that commit will probably be lost as well.
  * **GitHub:** A free (for basic use) service for storing git repositories online. Usually the online repository will be considered the master ("origin") copy.
  * **GitLab:** An open-source online Git repository service, which we're using instead of GitHub because they allow private repositories with their free accounts (and we don't want to deal with having public repos just yet).
  * **Bitbucket:** Another fairly popular online Git repository service. More geared towards professional projects.
  * **README:** While generally useful, they are especially helpful in repositories on GitHub or another online repository site
  * **.gitattributes:** Allows you to detail how git will treat different types of files. For example, DXF files are in a pseudo-text format, but are unreadable to people. So, you might put a line <code>*.dxf -text diff merge=binary</code> in .gitattributes for the repo. This tells git to not normalize the line endings (-text), find differences in the file as though it was text (diff), but don't show those changes to the user, and not trying to merge conflicts as though this was a text file (merge=binary).
  * **.gitignore:** Allows you to specify patterns for files or folders to ignore. On Windows machines, for example, Thumbs.db should always be in your .gitignore so that it doesn't get copied around (and probably corrupted) since the OS will generate that itself anyway/

It may be helpful to remember that each repository is a kind of with a head pointer pointing to a particular commit. Each time you "checkout" something, the head of your local repository is reassigned to another branch or another commit on the same branch.
-----
====How We Use It====
-----
GitLab lets us keep our code projects and board designs (Eagle Files are just XML, so they work great in git) in a central location and keep track of versioning. We have a BYU-Holography group on GitLab which contains the following repositories, among others. 
  * Arduino_EDID - For writing the EDID chip on DVI/VGA breakout boards from the Arduino.
  * Arduino_GalvoTest - For testing the galvo control on the Scanner Shield
  * Arduino_ScanShield - For running the Scanner Sheild - has an autolocking branch.
  * ArduinoMonitorFirmware - Arduino code for the now-deprecated Monitor shield (replaced with the Scanner Shield)

We have switched from GitHub (which is more commonly used but somewhat more expensive) to GitLab in order to have private repositories. You will either need a GitLab account (which will be added to the group) or have your SSH key in one of ours in order to access the repositories there. 
-----
====Using GitHub Desktop (Windows)====
-----
===Creating a New Repository===
On the CLI, there's a few steps to this:
  * "init" the new repository in the folder with your code
  * "add" the contents of that folder for the first commit
  * "commit" for the first time
  * "remote add" the remote repository URL
    * The remote repo needs a name. The one on GitLab should be called "origin"
    * In our setup, the URL for a remote repo called "name" would be <code>https://gitlab.com/BYU-Holography-HoloMonitor/name.git</code>
    * To access the repo over SSH, you would instead put <code>git@gitlab.com:BYU-Holography-HoloMonitor/name.git</code> - this method will allow access even if you don't have a GitLab account as long as someone who does stores your SSH public key.
  * "push" the first commit to the origin (the online repo on GitLab)

The Desktop Interface makes this easier for us:
  - With the program open, hit this plus to open the popup for creating/adding/cloning repos:\\ {{:jesse:gitguide:add1.png|}}
  - In this page, give it a name and specify where it is on the computer (can be local or remote, and can be an empty folder), and hit "create". It will always be in a floder matching the repo name.\\ {{:jesse:gitguide:add2.png|}}
  - Now you'll see this page with the local repo. GitHub Desktop keeps track of changes for you, so you won't have to "add" anything. If you see this dot, you have changes. \\ {{:jesse:gitguide:add3.png|}}
  - Here on the changes page, you'll see everything that has changed since the last commit. Since we just created this repo, everything is new. Every commit has to be given a "message" or name. Give the first one a name and commit it.\\ {{:jesse:gitguide:add4.png|}}
  - With that commit done, now we need to get this repo up onto GitHub. If you select a commit from the list, it'll show you the changes made in that commit. If you do this on the CLI, you'll have to create the repo online first. The GUI will take care of it for us, we just have to "publish" it. \\ 
    - Since we're now using GitLab instead, we'll have to do just a touch of manual work to finish the setup. First, create the repo online at [[https://gitlab.com/BYU-Holography]]. Then, right-click the local repository in GitHub Desktop and select "Open in Git Shell". Once it comes up, the command you want should be,replacing [URL] with the URL of the repo: <code>git remote add origin [URL]</code> \\ {{:jesse:gitguide:add5.png|}}
  - Here you'll give the GitHub repo a name (doesn't necessarily have to match the folder it's stored in), and a public description. Also, make sure you select which account it will be stored under (it will default to whomever's signed into the program, but we can select "BYU-Holography" from the dropdown).\\ {{:jesse:gitguide:add6.png|}}
\\ And with that, it's DONE!

===Making Changes/Updating Code===
  - With each new change, you have to "add" the changes to the next commit. The GUI takes care of that for us by just telling us when there's changes by giving us this dot: \\ {{:jesse:gitguide:changes.png|}}
  - Clicking on the "Changes" button takes you to the commit page. Here, you can select which changes are included in this commit (clicking on them will show you the details), give the commit a name (required) and description (optional), and commit it to your working branch. \\ {{:jesse:gitguide:commit.png|}}
  - Important to note is that this only committed the changes to the local repo. Now it needs to be "push"ed to the origin (GitHub/GitLab). The GUI combines "push" and "pull" into one "sync" button. Hit that after each commit, and anytime new changes may have been pushed to the origin by someone else\\ {{:jesse:gitguide:sync.png|}}
===Fixing Mistakes===
  * You can always "checkout" to a different commit or branch at any time. In the GUI, this is done by clicking on it on the branch's timeline, or selecting the branch from the dropdown (new branches can be made that way as well). \\ {{:jesse:gitguide:timeline.png|}}
  * Here, I've made a bad change. That missing semicolon is going to be a problem. So, we'll have to fix it. If we click this "Revert" button, git will create a new commit undoing the changes in this one. We can do that for any commit, but it will only undo that ONE commit, not necessarily the intervening ones. If you want to extract the file at that time, it's better to "checkout" that commit, extract the file, then return to where you were.\\ {{:jesse:gitguide:bad.png|}}
  * Since this was simple, revert is sufficient, so you can see it undone here: \\ {{:jesse:gitguide:reverted.png|}}

===Getting the SSH Key for GitHub Desktop===
The program should generate its own SSH key during install or first run. The key pair should be found in <code>C:\Users\[username]\.ssh\</code> and have two files: "github_rsa" and "github_rsa.pub". Don't touch the one without an extension: that's the private key. If you load the public key into your GitLab account (or that of anyone with access to the group), you'll be able to access the repositories over SSH wihtout having to log in. Over HTTPS, you always have to log in with a username and password.
-----
As a side note, GitHub desktop will NOT let you have multiple branches active on the same machine. From the CLI, you can have a different branches in different folders, you'll just have to rememeber which is which (or, if you're REALLY good, you can use git worktree, but that's still somewhat experimental)

====Using the command line====

Most of this is adapted from [[http://gitlab.com/help/gitlab-basics/README.md]].

===Setup===
Install git if it isn't already installed.

On your shell, type the following command to add your username:

<code>git config --global user.name "YOUR_USERNAME"</code>
Then verify that you have the correct username:

<code>git config --global user.name</code>
To set your email address, type the following command:

<code>git config --global user.email "your_email_address@example.com"</code>
To verify that you entered your email correctly, type:

<code>git config --global user.email</code>

Next, generate an SSH key pair if there is not already one on your computer. ([[https://gitlab.com/help/ssh/README.md]]). To add the public key to your gitlab account, copy it, go to your User Settings > SSH Keys, paste it in the Key box, add a title, and save it (screenshots of this process here: [[https://gitlab.com/help/gitlab-basics/create-your-ssh-keys.md]]).

===Starting a project===

===Setting up a local branch for the first time===
To create a local copy of the repository in "directory", run this command. You can leave out the directory argument, and it will make a new directory automatically.
<code>git clone git@gitlab.com:BYU-Holography-Leia/image-capture.git directory</code>


===Checking out===

To checkout master, do this:
<code>git checkout master</code>

===Create branch===

If you're going to make changes, first make a branch of the project, then when you're ready, merge that branch back in.

Create branch:
<code>git checkout -b branch_name</code>
or
<code>git branch branch_name
git checkout branch_name</code>

If you do this and then want to work on the master branch again, then make sure to commit changes to your new branch before checking out master again.

===Merging===
When you have made your changes in a branch and want to put them into the master branch, you do a merge.
First get back to master, by checking it out, then run git merge. This merges the branch specified in the command into the currently checked out branch.
<code>git merge branch_name</code>

In the case that your new branch is directly ahead of the master, it will just do a fast-forward, applying all those changes. If master has had commits since you branched from it, then you will need to resolve the differences.

After merging, you can delete the old branch (if you're done working on it):
<code>git branch -d branch_name</code>
This will delete your local branch but not the remote. To do that, add a colon before the branch name.

===Merge conflicts===

[[https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging]]
ElectroHolography Laboratory

User Tools

Site Tools

Page Tools
