-
Notifications
You must be signed in to change notification settings - Fork 0
Using Git
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 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.
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.
NOTE: As of now, we are naming our branches as (version number)-stable and (version number)-test. Any experimental code must be done in the test branch, and any approved changes that have passed a set of given test cases will be merged to the stable branch. We will be updating this when more standard guidelines are developed.
If a Github branch is too far ahead by accident and really should be behind a few commits,
git push [email protected]:USU-Robosub/Poseidon.git +e7e4eb58440e8d7009e406c8b86b0f91358c6e9f^:master
can fix it. Replace the hex with the child of the commit that you want to revert to.
Potentially helpful links:
http://christoph.ruegg.name/blog/git-howto-revert-a-commit-already-pushed-to-a-remote-reposit.html
http://www.git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging
http://www.git-scm.com/book/ch3-5.html
https://stackoverflow.com/questions/4114095/revert-to-a-previous-git-commit
https://stackoverflow.com/questions/927358/how-to-undo-the-last-commit