Icecast Server/Git workflow: Difference between revisions

From XiphWiki
Jump to navigation Jump to search
(Update: And changed the info URLs as well)
 
(10 intermediate revisions by 5 users not shown)
Line 3: Line 3:
== Repositories ==
== 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.
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"
{| class="wikitable"
|Name
!Name
|Anonymous access URL
!Anonymous access URL
|SSH URL (only project members)
!SSH URL (only project members)
|Comments
!Comments
|-
|-
|[https://git.xiph.org/?p=icecast/icecast.git Icecast server]
|[https://gitlab.xiph.org/xiph/icecast-server Icecast server]
|<code><nowiki>https://git.xiph.org/icecast/icecast.git</nowiki></code>
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-server.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast/icecast.git</code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-server.git</code>
|
|
|-
|-
|[https://git.xiph.org/?p=icecast/ices.git IceS]
|[https://gitlab.xiph.org/xiph/icecast-ices IceS]
|<code><nowiki>https://git.xiph.org/icecast/ices.git</nowiki></code>
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-ices.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast/ices.git</code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-ices.git</code>
|
|
|-
|-
|[https://git.xiph.org/?p=icecast/libshout.git libshout]
|[https://gitlab.xiph.org/xiph/icecast-libshout libshout]
|<code><nowiki>https://git.xiph.org/icecast/libshout.git</nowiki></code>
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-libshout.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast/libshout.git</code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-libshout.git</code>
|
|
|-
|-
|[https://git.xiph.org/?p=icecast/directory.git Icecast directory]
|[https://gitlab.xiph.org/xiph/icecast-directory Icecast directory]
|<code><nowiki>https://git.xiph.org/icecast/directory.git</nowiki></code>
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-directory.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast/directory.git</code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-directory.git</code>
|As seen running on http://dir.xiph.org - soon™
|As seen running on http://dir.xiph.org - soon™
|-
|-
|[https://git.xiph.org/?p=icecast/common.git Icecast shared code]
|[https://gitlab.xiph.org/xiph/icecast-common Icecast shared code]
|<code><nowiki>https://git.xiph.org/icecast/common.git</nowiki></code>
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-common.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast/common.git</code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-common.git</code>
|No need to check out separately, see below.
|No need to check out separately, see below.
|-
|-
|[https://git.xiph.org/?p=icecast/m4.git Icecast shared autofoo]
|[https://gitlab.xiph.org/xiph/icecast-m4 Icecast shared autofoo]
|<code><nowiki>https://git.xiph.org/icecast/m4.git</nowiki></code>
|<code><nowiki>https://gitlab.xiph.org/xiph/icecast-m4.git</nowiki></code>
|<code>ssh://git@git.xiph.org/icecast/m4.git</code>
|<code>ssh://git@gitlab.xiph.org/xiph/icecast-m4.git</code>
|No need to check out separately, see below.
|No need to check out separately, see below.
|}
|}
Line 46: Line 46:
First you need to clone the Git repository, because we use submodules, these should also be cloned, do to this, run:
First you need to clone the Git repository, because we use submodules, these should also be cloned, do to this, run:


<code><pre>git clone --recursive ssh://git@git.xiph.org/icecast/icecast.git</pre></code>
<nowiki>git clone --recursive https://gitlab.xiph.org/xiph/icecast-server.git</nowiki>


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


<code>
<nowiki>git clone https://gitlab.xiph.org/xiph/icecast-server.git</nowiki>
<pre>git clone ssh://git@git.xiph.org/icecast/icecast.git
cd icecast-server
cd icecast
git submodule update --init
git submodule update --init</pre>
</code>


== Initializing the Submodules ==
== Initializing the Submodules ==
Line 62: Line 60:
First of all, checkout the master branch, depending on your git version, your modules may be initialized in a detached HEAD state.
First of all, checkout the master branch, depending on your git version, your modules may be initialized in a detached HEAD state.


<code><pre>git submodule foreach git checkout master</pre></code>
  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>)
(If your git version does not support this, <code>cd</code> into each submodule and run <code>git checkout master</code>)
Line 73: Line 71:
First you need to commit the changed you made in the common submodule, so <code>cd</code> into it, and do
First you need to commit the changed you made in the common submodule, so <code>cd</code> into it, and do


<code><pre>git status</pre></code>
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.
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:
You could either do <code>git add .</code> or even shorter:


<code><pre>git commit -a</pre></code>
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.
The <code>-a</code> or <code>--all</code> option will add all changed or deleted files, but not add any untracked files.
Line 86: Line 84:
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:
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:


<code><pre>git remote set-url origin ssh://git@git.xiph.org/icecast/common.git</pre></code>
<nowiki>git remote set-url origin ssh://git@gitlab.xiph.org/xiph/icecast-common.git</nowiki>


Now push the changes to the remote location:
Now push the changes to the remote location:


<code><pre>git push origin master</pre></code>
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).
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).
Line 96: Line 94:
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:
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:


<code><pre>git commit -a</pre></code>
git commit -a


Now enter a meaningful commit message. (Yes, I sound like a broken record, but this is important)
Now enter a meaningful commit message. (Yes, I sound like a broken record, but this is important)
Line 102: Line 100:
Push the stuff to the remote:
Push the stuff to the remote:


<code><pre>git push origin master</pre></code>
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>)
(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>)
Line 111: Line 109:
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:
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:


<code><pre>git pull</pre></code>
git pull


and
and


<code><pre>git submodule update</pre></code>
git submodule update


to make sure submodules are up to date too.
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]]

Latest revision as of 15:23, 12 April 2021

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.