Icecast Server/Git workflow

The Icecast project recently migrated from Subversion to Git, this page outlines how to get started with it!

Repositories

The repositories are at git.xiph.org and are mirrored to GitHub. All repository names start with "icecast-" for clarity.

Name	Anonymous access URL	SSH URL (only project members)	Comments
Icecast server	https://gitlab.xiph.org/xiph/icecast-server.git	ssh://git@gitlab.xiph.org/xiph/icecast-server.git
IceS	https://gitlab.xiph.org/xiph/icecast-ices.git	ssh://git@gitlab.xiph.org/xiph/icecast-ices.git
libshout	https://gitlab.xiph.org/xiph/icecast-libshout.git	ssh://git@gitlab.xiph.org/xiph/icecast-libshout.git
Icecast directory	https://gitlab.xiph.org/xiph/icecast-directory.git	ssh://git@gitlab.xiph.org/xiph/icecast-directory.git	As seen running on http://dir.xiph.org - soon™
Icecast shared code	https://gitlab.xiph.org/xiph/icecast-common.git	ssh://git@gitlab.xiph.org/xiph/icecast-common.git	No need to check out separately, see below.
Icecast shared autofoo	https://gitlab.xiph.org/xiph/icecast-m4.git	ssh://git@gitlab.xiph.org/xiph/icecast-m4.git	No need to check out separately, see below.

The repositories were migrated with their full history, but for reference the old subversion repository structure remains browseable and all subprojects can be checked out below http://svn.xiph.org/icecast/trunk/<projectname>. This might be useful in case of some branches (not all were migrated) and no longer maintained projects that were not migrated to Git.

Cloning the Repo

First you need to clone the Git repository, because we use submodules, these should also be cloned, do to this, run:

git clone --recursive https://gitlab.xiph.org/xiph/icecast-server.git

If your Git version (git --version) is lower than 1.6.5, do:

git clone https://gitlab.xiph.org/xiph/icecast-server.git
cd icecast-server
git submodule update --init

Initializing the Submodules

The steps we did above, for cloning, initialized the Submodules, but if you want to do any changes to them and push them back to the remote repository, we need to set them to a specific branch, in this case, master.

First of all, checkout the master branch, depending on your git version, your modules may be initialized in a detached HEAD state.

 git submodule foreach git checkout master

(If your git version does not support this, cd into each submodule and run git checkout master)

Pushing changes to a remote Server

When you are done with some super cool new feature, or even while working on it, you may want to push your current state to the remote repository, so others can test it and give you some Feedback! For this example let's assume you've built an ACL, therefore changed something in httpp.c which is in the common submodule and changed a lot of stuff in parent repository.

First you need to commit the changed you made in the common submodule, so cd into it, and do

git status

This will list you the changes you made, each change you want to have in the commit needs to be added, let's assume (which is the most common case) you want to commit all changes. You could either do git add . or even shorter:

git commit -a

The -a or --all option will add all changed or deleted files, but not add any untracked files.

Now enter a meaningful commit message, the first line should be a rough summary, followed by two newlines and a more verbose description. Less is not more in this case, that’s what the summary is for.

Ok now it's time to push the changes to the remote server, if this is the first time you do this, you might need to set the origin url, because it defaults to a http(s) one, so that people without ssh access can clone the repository and submodules too, but for cloning you want to use ssh. Let’s set the remote origin like this:

git remote set-url origin ssh://git@gitlab.xiph.org/xiph/icecast-common.git

Now push the changes to the remote location:

git push origin master

This tells git to push your copy of the master branch to the remote location origin (that we’ve just set to the right url).

Ok now that we cared about the submodule, let's cd back into the parent repository, and commit the changes we made there:

git commit -a

Now enter a meaningful commit message. (Yes, I sound like a broken record, but this is important)

Push the stuff to the remote:

git push origin master

(If you are on a different branch than master, you probably want to replace master with the branch you are on, obviously, or just do git push)

NOTE: Even if you hadn't changed anything in the parent repository but just in the submodule repository, you would need to commit the change of the version of the submodule to the parent repository. If you just had updated the httpp.c you still would needed to do git commit -a -m "Update commons to recent version for latest httpp changes", and push it, to make the parent repository point to the right submodule version.

Updating the local repository

Let's say someone else committed something and pushed it, and you want to update your local copy to the one of the remote. Let's assume you have nothing changed, so you are just a bit behind in history, then it is a simple as:

git pull

and

git submodule update

to make sure submodules are up to date too.

If something changed, then git needs to reconcile the local changes and the remote changes. We prefer to avoid merge commits, unless there is a larger branch developed feature.

This can be either accomplished by always running:

git pull --rebase

Or by setting up git to do this automatically for you. The following passage is taken verbatim from Marcin Kulik's blog post on the same topic

In git >= 1.7.9:

git config --global pull.rebase true

In git < 1.7.9:

git config --global branch.autosetuprebase always

The latter has the effect of automatically adding branch.<name>.rebase true for each checked out local branch that is tracking an upstream branch to the repository config file.

Note that if you have both options set (not really recommended) then branch.<name>.rebase true that is automatically added for each branch takes precedence over global pull.rebase true.