Skip to content
This repository has been archived by the owner on Feb 13, 2018. It is now read-only.

Adding the SAAS libraries to your repository

Jump to bottom
strugee edited this page Sep 14, 2014 · 3 revisions

This page will show you how to add the libraries repository into your repository.

Introduction to Git submodules

SAAS recommends that you use Git submodules to embed our libraries into your repository. Simply copying and pasting is not the ideal situation and is not recommended.

Git submodules are essentially a way to embed a Git repository within a Git repository. Submodules are made up of two things: a remote URL, and a SHA1 commit id. When you clone a repository and initialize the submodules, Git will clone the URL into the specified path, then cd into the new directory and check out the specified commit. For example, you might have a submodule that has a path of "Libraries", a remote URL of git://github.com/saasrobotics/Libraries.git, and a commit id of a55236c4af35ea0383b721cde3e255d766b34698. For a setup like this, Git will initialize the submodule by doing the equivalent of the following:

  1. git clone git://github.com/saasrobotics/Libraries.git Libraries
  2. cd Libraries
  3. git checkout a55236c4af35ea0383b721cde3e255d766b34698

For more information about submodules, consult the git-submodule(1) manpage, along with the Pro Git section on submodules.

Importing the libraries

Importing the libraries is fairly easy. You will need to use the Git shell for the initial import, but after that, you should be able to use the GitHub app.

  1. Open the GitHub app and find the repository that you want to import into. For SAAS team members, this is probably your team number under the saasrobotics organization on GitHub.
  2. In the upper-right, click the gear icon, then click "Open in Git Shell"1.
  3. Execute the following command: git submodule add git://github.com/saasrobotics/Libraries.git $target2, replacing $target with whatever directory name you want the libraries to be cloned into. A good choice for this might be libraries or Libraries. (To execute a command, type it into the prompt and press enter.)
  4. (Optional) Choose a specific revision of the libraries that you wish to use by executing cd $target, followed by git checkout $commit, replacing $commit with the desired revision. Then type cd .. to return to the main repository.
  5. Commit your results. You may do this from either the shell or from GitHub for Windows, but you must make sure to commit both the .gitmodules file and whatever $target is. If you do not commit both of these files, your submodule will not work on other computers.

Performing maintenance on your submodule

Footnotes

1: These instructions were designed for GitHub for Windows 2.x. The interface may be different in future GitHub for Windows versions, or in GitHub for Windows 1.x. Using GitHub for Windows is not required if you prefer to use Git differently; all you need is a shell that can use the git command.

2: If for some reason you would like a read-write submodule instead of a readonly submodule, use git submodule add git@github.com:saasrobotics/Libraries.git $target (if your team tends to open the Git Shell from GitHub for Windows) or git submodule add https://github.com/saasrobotics/Libraries.git (if your team tends to open the Git Shell from something other than GitHub for Windows). If in doubt, choose the first one.

Creative Commons License
SAAS Robotics wiki by SAAS Robotics members is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Clone this wiki locally