Using GIT with Arduino

 

What is GIT?

The term GIT doesn't actually mean anything. It was made up. But what it is, is a "version control system". That sounds complicated, but really all it boils down to is that it saves versions of your files, and gives you a way to revert back to old versions - if necessary.  It also provides a way for multiple developers to work on the same project, and even to keep the same project 'in sync' between computers no matter where they are.

Where do I get it? 

In order to use GIT, you need to install it. Many IDE's come with it pre-installed, but unfortunately, the Arduino IDE does not. You can find downloads for Windows, Mac, or Linux here:

https://git-scm.com/downloads

I will note, however, that GIT is generally a Command-Line tool. There are GUI's also available on the same website. If you need a GUI, then you can get one there. You should first learn the basic commands for GIT before using a UI though. 

Once you download and install it, you can start using GIT. 

Your First GIT Repository

To use GIT with Arduino, open your command prompt and navigate to the folder where you have any project stored. Then while you're inside that folder type:

git init

That creates the *local* repository called '.git'. But nothing is in it yet, and it only exists on your own machine.

There may be an instance that you want to not include certain files or folders in your git repository.
If you'd like to do that, you simply create a text file that's named '.gitignore' in the same directory as you just created your git repository. Notice that there is no extension to this file, and it starts with a period. 

Once you create this file, you can add file names, folder names, or even wildcards with extensions to make git ignore certain files.

For instance, this will ignore '.gitignore', the folder named 'StuffIDontWantInGit' (and any content in that folder), any file with an '.exe' extension, and any file with a '.bat' extension. 
 

.gitignore

/StuffIDontWantInGit

*.exe

*.bat

Next, you have to put your files into it. 
You do this by typing:

git add --all

This puts a copy of everything in this folder into your local git repository with the exception of anything you've told it not to inside your .gitignore file. If you add any new files, you can just type this command again, git will put those new files into your repository. You can put anything you want in there. Sometimes, it's nice to save datasheets and other documentation. You can put that in there too. Git doesn't care what you put into it. It will store it all. 

If you'd like to see what files are in your git repository, then type:

 git ls-files

At this point, git is 'watching' any files you've added to it, but you still need to 'commit' them to the repository. This is when they're actually stored in there.

To do that, you need to type 

git commit -m "This is my first git commit."

The -m here along with the message is required. It's where you type a short concise message about what changes you've made to your code. Normally, you'll type something like 'fixed a bug in sensor reading' or something like that. It's there to give you memory about what you changed, in case you need to revert back to an older version later. 

Now, when you change your Arduino file, you'll need to commit those new changes to your git repository by navigating to this folder and typing a slightly different command to import your changes into the repository. The '-a' will detect the changes in the files, and replace the correct file in the repository with your changed file. 

git commit -a -m "I changed the setup loop" 

OK, Now what?

Well, you could just save that .git folder somewhere, and then put it in a new folder later and (from inside that new directory) type 

git checkout HEAD~1

That will restore the files that you previously stored in your local repository. 

But it's much more common to add a remote repository and 'push' your code to it. 

There are any number of free and paid online GIT repositories that you can use. You can even host your own server. They all work more-or-less the same, although some of them require different login schemes. One of the most popular, is GitHub.com, which is currently owned by Microsoft.

In order to use GitHub, you'll have to create an account there. 
Once you do that, you click "New" to create your new online repository for your awesome project. 

Then, give your new repository a name, and if you'd like to add a description, do that too.

Now, you've got a few choices to make. The most important choice is whether or not to make this repository public, or private. If you want to share it with anyone, then it should be public. If you only want to control who is allowed to see your repository, then make it private. Not all online repositories have these settings. Some only allow private repositories, and some only allow public repositories. 

You can allow GitHub to create a README file for your repository. We could have done this ourselves too. If you have a README file, GitHub will display it to anyone who has access to your page. It's a really good place to leave yourself notes about what your code does, what it might run on, or anything else you might forget after not looking at it for a while. 

You can also add a .gitignore file here. We already did that, but if you didn't add one, you can do it here. 

Finally, you can choose a license. If your repository is private, I don't think this matters. If your repository is public, you might want to choose a license for your code to allow (or disallow) other people to use your code. I'm not a lawyer, so I'm going to pass on saying much more than that. 

When you're done, click 'Create Repository'.

Once you do that, you'll see your new repository. If you want, you can edit your README right there on that page. 

 At this point your new repository is still empty. We'll need to connect our local repository to our online repository and push our code to it. 

You do this by opening a terminal in your Arduino folder, then typing:

git remote add origin https://github.com/user/repo.git

Where 'user' is the username you used when you created your GitHub account, and repo is the name you gave to your new repository. Don't forget to add the '.git' at the end. 

Now, push your code to your remote repository with a 'git push' command.

This command will push the code that you've previously put into your git repository to your new repository on a branch called 'master'. You can change that branch name if you'd like to use something else. It's also useful to create separate branches for your code (and you can merge them back together later if you'd like). Mostly, I use those branches to keep multiple projects in a single repository. It's not uncommon to have an Arduino project that also has a related web server or Android project. You can use those branches to keep all of those projects together. 

It's also not that uncommon to clone this repository onto another computer. That might be another computer you own or your coworker's computer. Either way, it's the same. 

To do this, go to the folder where you'd like to create the clone folder. Open a git terminal, and type:

Note that 'master' in the command is the name of the branch you typed when you pushed the files to the remote repository earlier. If you omit this, it will default to a branch called 'main'.

Now, when you make any changes in any of your files, use 

git commit -m 'I changed these files'

to add the files to the LOCAL repository, then use

git push

to push those changed files to the SERVER. 

When you or your coworker opens the folder on their computer, they'll type:

git pull

Which will pull down any changes from the remote repository, syncing your code. 

Good luck, and Happy Coding!
~Tom