HCI Data Source: markdown, Import: https://git.nordwest.freifunk.net/ffnw-puppet/puppet/raw/master/README.md, Section:

Puppet base Repository

This is the main repository for puppet deployment in the Freifunk Nordwest community. We call it the puppet base-repository. It contains the file structure for your /etc/puppetlabs/code-Folder. The content of the base repository is split up into several parts that are maintained using git submodules:

For seperating development and production from each other we use git branches. So please use the master branch of this repository if you want to get a development environment and the production branch if you want to get a production environment. But please note that in both cases the puppet environment will be production so if you want to deploy different branches you will have to deploy them on different puppet masters. We agreed to use this concept for ease and security reasons.

Using this repository

Using this repository differs from using a standard git repository so please take your time and read the following carefully!

How to clone

This repository should be cloned as a replacement of your /etc/puppetlabs/code-folder. When cloning, you normally want to clone a special branch (-b) and all submodules (--recursive) at once:

git clone --recursive git@git.nordwest.freifunk.net:ffnw-puppet/puppet.git /etc/puppetlabs/code

If you forgot to use --recursive you can use git submodule update --init to init the submodules for the first time.

Preparations for developing on a submodule

After you cloned the base repository with --recursive it will point to the branch you checked out. But all submodules will be in detached HEAD state and point to the last commit their commit reference has been configured to. In a production environment you can leave this as is. But when developing on a submodule, you want to change into the directory of the submodule and checkout the branch you want to work on before you start developing:

cd path/to/submodule/
git checkout <branch>

If you want to checkout a certain branch on all submodules at once you can use the following command inside the base repository:

git submodule foreach git checkout <branch>

Please note: the base repository and it's submodules should always be checked out on the same branch except you know what you are doing!

How to commit

If you changed something you can commit your changes by using the standard commit command from inside the submodule you want to commit your changes to

git commit -sam 'Your change'

If you committed a change to the base repository you can push your changes now. But if you did a commit to a submodule there is a second step to take. A commit to a submodule will change the reference from the base repository to the submodule. So after doing a commit to a submodule you need to switch to the base repository and do a second commit to update the commit references

cd ..
git commit -sam 'Update commit references'

Please note: if you want to see whats going on you can use git submodule status, git status and git diff to view the changes before committing.

After you have finished committing, you can push your changes.

How to push

To push all changes made to the base repository and it's submodule repository change to the base module and use the following command

git push --recurse-submodules=on-demand

Update base repo and submodules to configured commits

If you want to update the base repository and all submodules to the commits that have been configured for the submodules in the base repository, you first need to update the base repository and afterwards you need to update all submodules:

git pull --rebase
git submodule update --remote

If you checked out a submodule to a certain branch and want to update this branch, you can use git pull inside the submodule.

Update base repo and submodules to latest master

In the base repo do:

git pull --rebase
git submodule foreach git checkout master
git submodule foreach git pull
git status
git submodule status
git commit -sam 'Updated commit references to submodules'

Making changes in a submodule (summary)

We hardly recommend to read the whole documentation before reading the summary! To make changes to submodules you need to follow this steps:

  1. Clone the base repo including all submodules (git clone --recursive git@git.nordwest.freifunk.net:ffnw-puppet/puppet.git puppet)
  2. CD into the base repo (cd ./puppet)
  3. change into the submodule you want to edit (cd path/to/submodule/)
  4. checkout the branch you want to edit, this should be the same branch as the base repository branch (git checkout master)
  5. edit files
  6. commit your changes to the submodule (git commit -sam 'My changes')
  7. change to the base repository (cd ../)
  8. commit update of submodule reference to base repo (git commit -sam 'Updated commit referenced')
  9. push changes to base repository and submodule repo (git push --recurse-submodules=on-demand)

This process should result into two commits: one commit in the submodule repository and one commit in the base repository.

Merging changes from master into production

Active development takes place in the master branch. If a milestone is reached, you want to make all changes in the master branch become available in the production branch. Therefore you first switch the base repository to production branch

cd path/to/base/repository
git chekout production

Then you change into each submodule and execute the following commands

cd path/to/submodule/
git checkout master
git pull --rebase
git checkout production
git merge master
git push

After you have done this to all submodules you make a last commit to the puppet base repository to update the submodule references and push everything

git submodule status
git commit -sam 'Updated submodules: master2production merge'
git push --recurse-submodules=on-demand

If you dont want to do this everytime by hand, you can use the master2production.sh script.

Adding a new submodule

For adding a new module please read

Howto Submodules

For a general howto on git submodules pleas read


Git asks me for ssh key password very often

You can use ssh-agent to make ssh remember your password.