Setting up a new UserLib with GIT

This is a guideline for how to set up a new UserLib locally and at GitHub, and how to add it as a GIT submodule to the main jamoma GIT repository.

Create a new project at GitHub

  • Go here to set up the new repository. Give it the name that you would want the UserLib submodule to have, e.g. FooBar.

Set up the local GIT repository and push to GitHub:

You will probably get instruction on how to do this from GitHub once you have created the project, but for safety we are repeating them here, assuming that you have GIT set up already:

  • Create a new folder named FooBar.
  • Open Terminal and cd to the FooBar folder
  • Type in the following commands, substituting for your username and the name of the new repository:
git init
touch README
git add README
git commit -m 'first commit'
git remote add origin git@github.com:username/FooBar.git
git push origin HEAD

Add the new UserLib repository as a submodule to the Jamoma GitHub.

This part assumes that you have permissions to push changes to the main Jamoma repository. If not, please get in touch with the Jamoma developers and ask them to help you. The best way of doing so, is by posting a mail to the jamoma-devel mailing list. Alternately you can fork the Jamoma repository and then send us a Pull request as documented in http://github.com/guides/pull-requests .

Open Terminal, and change directory to the main Jamoma repository on your computer, and run the following commands:

git submodule add git://github.com/username/FooBar.git UserLib/FooBar
git submodule init
git submodule update
git status
git commit -m "Make a brief comment saying that you add a new UserLib and describe it." 
git push origin HEAD

Warning regarding the last step:

Be careful about what you commit and push in the top-level (what we are calling the 'umbrella' repository) and in what order you do this. Do not commit changes to the umbrella if submodules have changes registered that have been committed but not yet pushed because it will break things for others.

Tagging a UserLib folder

If you tag a revision in your repository, then Github will make a .zip available to download from the webpage. This is convenient for users that don't have a git client installed.

The following example shows how a tagging is done for the Tap.Tools UserLob folder:

   cd <path/to>/Jamoma/UserLib/Tap.Tools
   git tag 0.5.0-release
   git push --tags

Now go and look at http://github.com/tap/TapToolsForJamoma/downloads -- it's there as a zip.