Eastbots Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
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 find the Eastbots organization: https://github.com/Team-4795.

Once you have a github account, Amr, Steve, or Ilena can add you to the Eastbots organization in github.

====== 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  

====== Git basics, Steve's version ======
Here's a drawing that might help understand the basics:

{{ :git-flow.png |}}

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. 

Here's a screenshot showing the complete process.  We change into a folder (directory) that already exists called Eastbots, and run "ls" only to find that it is an empty folder.  Then we do the clone, and ls again.  We see that a new directory called pcboards-2018 has been created.
{{ ::git-clone-pcboards.png?400 |}}

===== 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 "''git pull''"

Unless you only did your clone seconds ago, someone else on the team may have submitted changes since you cloned.  Run ''git pull'' early and often to stay up to date!

===== aside: your first edit =====

Exercise:
  * Clone the Team-4795/pcboards-2018 repository  (see git clone above)
  * find the file gitplay/team-git-practice-file that was copied to your computer
  * Using a text editor (like textedit, notepad, emacs, or vim), add one new line to the file that contains at least your name.  Do not use word or any other word processor to edit these plain-text files.

These screenshots show what you'll see.  Use "cd" to change into the pcboards-2018 directory, and ls to list the files there.  Then cd into the gitplay directory (folder).  Running ls there shows that there's a file called team-git-practice-file there.  This is the file we want, so we run our text editor on that file.

{{ :git-cd-editfile.png?400 |}}

Some editors will run right in the terminal, others will start up a new window in which they can support
menus and mouse actions.  That can look like this:

{{ :git-editfile-emacs.png?300 |}}

===== git status =====
Git status shows what you've done in your working copy, listing files that have been changed or created.
{{ :git-status.png?400 |}}
In white is my prompt, where I typed the ''git status'' command and pressed return.  The important part of the output is in the middle, under "Changes not staged for commit".  Here one file has been modified, and its name is shown in red.

Exercise:
  * do the edit shown above, either from the command line or from a graphical file manager
  * open a terminal and find the team-git-practice-file again
  * run "''git status''" as shown above.


===== git add =====
When you've made a worthwhile change (say adding a new function or component), use "''git add'' //filename//" to "stage" the change in preparation for committing it permanently to the repository.

Exercise:
  * find team-git-practice-file again; the file that you changed above
  * stage your change by running:

    git add team-git-practice-file


===== 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.
{{ :git-commit-editor.png?400 |}}

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?)

To make a simple commit without using a text editor, you can put the message on the command line with the ''-m'' (message) option.  Be sure to put the message sentence in double quotes:
  git commit -m "added my two cents"

===== 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.  Here's what git push can look like:

{{ :git-push-nopw.png?400 |}}


Exercise:
  * Run ''git push'' to send your change up to github
  * Look at https://github.com/Team-4795/pcboards-2018/tree/master/gitplay to see your change and its message




====== 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 ======
  * https://www.youtube.com/watch?v=boeCjJKg-LY&t=0s&list=PLUSdSy9CkwBIiISFMa_ThWmtFCKtYLUE_&index=6 - Eastbots programming video focusing on git 
  * official git documentation and tutorial: https://git-scm.com/book/en/v2/Getting-Started-Git-Basics
  * another tutorial https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners