View source for 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 [https://git.xiph.org git.xiph.org] and are mirrored to [https://github.com/xiph GitHub]. All repository names start with "icecast-" for clarity.
{| class="wikitable"
|Name
|Anonymous access URL
|SSH URL (only project members)
|Comments
|-
|[https://git.xiph.org/?p=icecast-server.git Icecast server]
|<code><nowiki>https://git.xiph.org/icecast-server.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast-server.git</code>
|
|-
|[https://git.xiph.org/?p=icecast-ices.git IceS]
|<code><nowiki>https://git.xiph.org/icecast-ices.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast-ices.git</code>
|
|-
|[https://git.xiph.org/?p=icecast-libshout.git libshout]
|<code><nowiki>https://git.xiph.org/icecast-libshout.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast-libshout.git</code>
|
|-
|[https://git.xiph.org/?p=icecast-directory.git Icecast directory]
|<code><nowiki>https://git.xiph.org/icecast-directory.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast-directory.git</code>
|As seen running on http://dir.xiph.org - soon™
|-
|[https://git.xiph.org/?p=icecast-common.git Icecast shared code]
|<code><nowiki>https://git.xiph.org/icecast-common.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast-common.git</code>
|No need to check out separately, see below.
|-
|[https://git.xiph.org/?p=icecast-m4.git Icecast shared autofoo]
|<code><nowiki>https://git.xiph.org/icecast-m4.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast-m4.git</code>
|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 [https://trac.xiph.org/browser/icecast/ browseable] and all subprojects can be checked out below <nowiki>http://svn.xiph.org/icecast/trunk/</nowiki><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://git.xiph.org/icecast-server.git

If your Git version (<code>git --version</code>) is lower than 1.6.5, do:

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

== Initializing the Submodules ==
The steps we did above, for cloning, initialized the Submodules, <i>but</i> 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, <code>cd</code> into each submodule and run <code>git checkout master</code>)

== 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 <code>cd</code> 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 <code>git add .</code> or even shorter:

 git commit -a

The <code>-a</code> or <code>--all</code> 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@git.xiph.org/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 <code>cd</code> 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 <code>git push</code>)

<b>NOTE</b>: 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 <code>git commit -a -m "Update commons to recent version for latest httpp changes"</code>, 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 [https://coderwall.com/p/tnoiug/rebase-by-default-when-doing-git-pull 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.''

[[Category: Icecast]]