This is an old revision of the document!
Table of Contents
Git is a piece of software called a “version control system” or “revision control system”.
The electrical team is using git for our work with schematics and printed circuit board design. The software team is using it for robot code. Both teams are creating and changing many computer datafiles, which they need to share and track. Version control systems make it easy to keep track changes to files, to back up to old versions if a mistake is made, and to coordinate changes among many users.
Github is an online service that provides two main things (an lots of others): git repositories “in the cloud”, and a bunch of web features built on top of git. FIRST gives teams good githup accounts, so we're using it.
Before doing anything, sign up with github (create a username and password, and join the Eastbots organization: https://github.com/Team-4795. (does someone have to invite team members so they get permission on Team-4795?)
Installing Git
If you're using linux, git should be available easily with the software package manager in your linux system. We found a good windows download here https://git-scm.com/download/win (Ilena, is this the one we put on yoru computer?)
Git basics, Steve's version
Here's a drawing that might help understand the basics:
And here's another: https://commons.wikimedia.org/wiki/File:Git_data_flow.png
git clone
Clone is used to copy an existing repository - typically to get your own local repository from the “parent” one in the github cloud. You follow the clone command with the URL or path to the existing repository, for example:
git clone https://github.com/Team-4795/pcboards-2018.git
to put a copy of the pcboards-2018 tree onto your own computer. Get the link to the existing repository from the green “clone or download” button in the repository's github page.
git pull
The pull command updates your local repository and working copy with new changed made and pushed to the parent repository on github. Simply type “<tt>git pull</tt>”
git status
Git status shows what you've done in your working copy, listing files that have been changed or created. (TODO screenshot of git status output)
git add
When you've made a worthwhile change (say adding a new function or component), use “<tt>git add</tt>filename” to “stage” the change in preparation for committing it permanently to the repository.
git commit
Commit makes permanent all of the changes that you have staged with the git add command. It stores your changes as a new version in your local repository. After typing git commit, git will start up a text editor for you to type in a commit message describing what you changed. The first line of the message should be a brief summary. Then leave a blank line, and possibly describe the reasons for the changes in more detail. Good commit messages help your teammates (and you) understand why the program or design was changed.
(screenshot of editor plus commit message)
On linux, the text editor that git starts for the commit message can be changed with the $EDITOR environment variable. (how does this work on windows?)
git push
The last step in doing a useful addition to a project is to push it up to github so the world (and your teammates) can see it. Type “git push”. You'll have to type in your github password every time.
The only way I know to avoid typing in your github password with every commit is to do your initial clone using ssh, and also create and upload your ssh public key to github. But ssh doesn't work inside the firewall at ECHHS, so best to learn your github password.
Daily Use of Git
Before you start working for the day or session, do “git pull” to download everyone else's changes.
As you pause for the end of the day, or finish somthing big, do “git commit” followed by “git push” so that everyone else can see your work.
References
- official git documentation and tutorial: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics