Using Git

Intro

I thought I should make a quick blurb about how to use Git properly, at least in the Linux command-line. GUIs are available for those who want one, but I'll be talking about the CLI interface.

First, to obtain your own copy of the Poseidon repository, simply type:
git clone [email protected]:USU-Robosub/Poseidon.git

It's important to realize that in Git, there are no files, but rather that the state of the repository is the accumulation of changes to those files up to that point. Thus it's very possible to look at the files at any point in the past. This is easiest through the web interface, but is also possible to do yourself. That's why it's so important to commit working changes often; it makes changes organized and you can always revert to a working state.

Branches

Branches are a neat concept in Git, and they are best thought of as a line or path of commits (changes). Branches can be remote (on Github) or local to your computer, or both. Currently there are two branches that we have to work with here. First is master, which is the branch that contains the basic Ruby, API, and driver code. This is what most people will want to work on as it doesn't contain any extraneous code. However, when you clone the repository, you will not be looking at this branch.

To switch to the master branch, type:
git checkout master

Which will create a local master branch on your machine that reflects the remote master branch on Github.

We also have another branch, remote-control, that is based off of master but also contains client-server code for remote control of the submarine. Changes in master will be merged into remote-control, usually by Jesse.

If you are interested in working with the remote control code, switch to remote-control branch, via:
git checkout remote-control

Finally, this is usually an advanced thing, but if you would like to make a new branch for something (such as OpenCV, hydrophones, cameras, etc) and don't want to disturb anyone else's work, you can make your own branch. You can see more about how to do this on this guide.

Making changes

If you are working on a branch and would like to make your changes public to Github, it's pretty straightforward. First, do a git pull to ensure that you're up-to-date with the remote code on that branch. If there are conflicts, they need to be resolved. Otherwise, you are now ready to commit. You can look through your changes with git diff or git diff to remind yourself what you changed. Prepare them with git add -A, then commit with git commit -m "fixed a bug" or whatever your changes were. Please use a short but relatively descriptive message so that everyone knows at a glance what changes were made. Then push your changes to Github with git push.

I tend to commit whenever I finish a small to-do item, or a mental thought. It's usually one or two things, occasionally three. Commits are cheap, and its nice to see the accumulation of small changes as working code! If you have any questions, you can get in contact with Jesse.