As I have time I will be developing this thread into a crash course on Git for Arduino beginners. My plan is to structure it entirely as a hands-on exercise.
Install Git. This varies by operating system. In my case, I am using Windows 7. I installed TortoiseGit which is a very nice GUI on top of Git. The installation includes everything needed to get started.
This crash course only uses Git from the command-line. In my case, I will use Git Bash; a Linux like shell for Windows. If Git is installed correctly, the exact same commands should work in a Windows Command Shell.
Start by opening a command shell (e.g. Git Bash).
Navigate to the directory containing your Arduino sketch. I will be working with a sketch named "MotorThing".
cd /c/ProjectsSplit/Arduino15/Sketch/MotorThing
Create a repository for that directory...
git init
A directory named .git is added to the MotorThing directory. That directory is the Git repository.
Add all the working files to the index (note the dot at the end).
git add .
Every Git repository has an index. The index is essentially a list of pending actions. The command above puts a "please add all files in this directory" action into the index.
The index can be checked with the status command...
git status
On branch master
Initial commit
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: MotorThing.ino
At this point, nothing has actually been saved to the repository. More files can be added to the index. Files in the index can be removed. The index can be left in its current state.
When changes should be "saved" (commit in Git nomenclature) simply...
git commit
In my case, Visual Studio opens with this...
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
#
# Initial commit
#
# Changes to be committed:
# new file: MotorThing.ino
#
I have no idea how Visual Studio came to be the text editor Git uses. There is a mechanism to configure whatever editor you prefer.
In any case, a commit has comments. For this example I changed the file to...
Initial commit.
After saving the file and closing Visual Studio, Git responds with...
[master (root-commit) ce3a623] Initial commit.
1 file changed, 9 insertions(+)
create mode 100644 MotorThing.ino
And the index status is now...
git status
On branch master
nothing to commit, working directory clean
Or, the comment can be included in the command...
git commit -m "Initial commit."
After making changes to MotorThing.ino I am ready to commit. The index status is...
git status
On branch master
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: MotorThing.ino
no changes added to commit (use "git add" and/or "git commit -a")
Git recognizes that MotorThing.ino has changed. But, before those changes can be added to the repository the index has to be updated. As a nice convenience, Git supports updating the index and committing with one command; just add -a...
git commit -a -m "Start adding serial debugging."
[master 694013e] Start adding serial debugging.
1 file changed, 1 insertion(+)
Git status indicates the working directory and repository are synchronized...
git status
On branch master
nothing to commit, working directory clean
I make more changes to MotorThing.ino. I get busy. A week passes. I forget what I was doing. Git diff to the rescue...
git diff
diff --git a/MotorThing.ino b/MotorThing.ino
index 7e4ad40..d96e75d 100644
--- a/MotorThing.ino
+++ b/MotorThing.ino
@@ -2,6 +2,7 @@
void setup( void )
{
Serial.begin( 250000 );
+ Serial.println( F( "Hello world!" ) );^M
}
void loop( void )
The output is cryptic but well documented. It is possible to decipher what was changed. A better choice is to use something graphical; something that shows the "before" and "after" side-by-side. There are a plethora of tools available. For example, this is from TortoiseGitMerge...
Uh oh! I hit a dead end on this development path. And I've made so many changes. I desperately need to go back to the previous commit. No sweat. Git revert to the rescue.
First commit the current changes...
git commit -a -m "Bad news. Dead end. And a terrible mess."
[master 26ab4b4] Bad news. Dead end. And a terrible mess.
1 file changed, 1 insertion(+)
Then revert to the previous commit...
git revert HEAD --no-edit
[master 9de0d12] Revert "Bad news. Dead end. And a terrible mess."
1 file changed, 1 deletion(-)
If I later decide that the terrible mess was not so terrible I can actually pull the "bad news" commit out of the repository.
I've only recently discovered how easy git is to set up and use. My projects have been typically one- man developments, some large though, and I have usually worked by taking a snapshot of the full project, once testing has been completed on a set of updates, then making that snapshot the new version. This works but is clumsy and, in eclipse for example, results in huge work spaces which take ages to index.
This tutorial is also a good start: Git Tutorial
This work flow appears to be very useful in working with git: A successful Git branching model » nvie.com
Thanks for the additional suggestions and resources.