mini-howto setup and use a git server for kernel development

'git' is a version control system written by Linus. It is widely used by kernel developers. You can find tutorials and manuals from git.
This page is a brief description of how to use git to access a public server, sopc, which is created to host open-source projects of nios2 and alike. 

This server is located at the Embedded System Lab., Electronic Engineering Department, National Taiwan University of Science and Technology . The server was maintained by Mon-Chau Shie, who is an assistant professor of the Electronic Dept., NTUST. Best thank for his kindly support.
(The server is bebind a firewall, and you won't be able to ping.)

All contributions to kernel and u-boot should conform to the Linux kernel coding style; see the file "Documentation/CodingStyle" and the script "scripts/Lindent" in your Linux kernel source directory.

Use the git as a user (readonly)

As user on local machine,

1. install git-core package , as root or via sudo.  (Note, older git packages may have problem. v1.5.2 or higher is required. Try the latest version, or build it from source)
On Fedora,RHEL,  yum install git-core  ( for Centos rpms http://schwarzecker.homelinux.net/ )
On Suse, zypper install git-core gitk
On Debian,Ubuntu, sudo apt-get install git-core

If you have older version, try update. Or better, build from the latest git source, which is 1.5.3.8 at this time of writing.
You can check your installed git version with "git --version" .
If have older version and you want to build from source, uninstall or remove the old package.
http://www.kernel.org/pub/software/scm/git...1.5.3.8.tar.bz2

tar jxf git-1.5.3.8.tar.bz2 # extract to any directory outside uClinux-dist
cd git-1.5.3.8
./configure
make
sudo make install  # will install git to /usr/local/bin

2. As a user, download the source tarball. It is about 413MB, and it would take a while. Best thanks to Altera's kindly hosting these files.
Please do not clone from sopc server, as we have network loading issue at NTUST.
(sha1sum 238a4c9a4b5ccc7458119e06aedc9820d008a9a2  uClinux-dist-20080131.tar)
tar xf uClinux-dist-20080131.tar

cd uClinux-dist
ls
You won't be able to see any files yet, because all the files are compressed inside the hidden .git dir.
You can brow your local git using "gitk" GUI, which is included in git-core package.
gitk &

3. Find what branches are here and decide which branch to use,
git branch -a
  master
* nios2
  v2.6.23-uc
  origin/HEAD
  origin/fixme
  origin/master
  origin/nios2
  origin/test
  origin/v2.6.23-uc

git checkout master # uClinux-dist-20070130 stable, kernel v2.6.19
Or,
git checkout v2.6.23-uc   # uClinux-dist-20071107 development, kernel v2.6.23

Now you can see the sources like this,
ls
bin      Documentation  lib          linux-2.6.x  README  uClibc
config   freeswan       linux-2.0.x  Makefile     SOURCE  user
COPYING  include        linux-2.4.x  openswan     tools   vendors

4. STOP HERE. Go back to UClinuxDist . You should be able to build and run uClinux now.
make menuconfig
make vendor_hwselect SYSPTF=/path_to/your_system_ptf
make

The following step 5 and 6 are optional. They get the latest update patches. You should follow it ONLY AFTER the first successful build and boot.

---

5. Only if you are blocked by firewall to use git:// port 9418, you can use http:// instead. But it will be slower than using git:// . Don't use http:// unless you have no choice.
Edit file .git/config, and change [remote "origin"]  url to http:// .
[remote "origin"]
       url = http://sopc.et.ntust.edu.tw/git/uClinux-dist.git
       fetch = +refs/heads/*:refs/remotes/origin/*

If you are behind a http proxy firewall, you will need to add the setup of proxy to your login profile (.bash_profile or .profile)
export http_proxy=http://proxy_server:port_number


MIRRORS You can choose the mirror nearest to you and replace the url in remote "origin".

url = http://git.opensource.emlix.com/git/nios2/uclinux-dist.git (DE) gitweb = http://git.opensource.emlix.com/  . (Best thanks to emlix.com)


6. Get updates from git server,
git pull

If your Linux PC doesn't connect to internet, you won't be able to pull from the server. You can download the patches for master branch, and use "git am" to apply them (but don't use them on the other branches).
Apply them in the numbered sequences, and apply each patch only once. eg,
git am 0047-....patch
Note, patches 0001-0046 are already in the tarball uClinux-dist-20080131.tar, you should not apply them twice.

After getting the updates, make again. Sometimes, you may need to clean before make for the changes to take effect.
make user_clean
make

---

Use the git as a project contributors (can write)

(If you want to contribute, please send me ,Hippo, an e-mail attaching a public key for ssh access. ie, run 'ssh-genkey' and send me the file ~/.ssh/id_rsa.pub. Please also give me your real name and preferred user name on this server. This will allow you to push the git server.)

As user on local machine, setup your local git as described in previous section.

1. as a user, give your real name as it is a norm in Linux kernel mailing list.
  git config --global user.email "you@email.com"
  git config --global user.name "Your Name"

2. edit .git/config, add ssh to remote origin,

[remote "origin"]
       url = ssh+git://sopc.et.ntust.edu.tw/git/uClinux-dist.git
       fetch = +refs/heads/*:refs/remotes/origin/*

3. edit, test, commit...
Please add signoff (-s) to your commits. Please add "nios2:" to the commit message of nios2 arch specific patches, or names of the subsystem or drivers otherwise. See http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#creating-good-commit-messages

git status  # check which files should be committed
git diff the_files_or_subdir_to_be_updated  # double check the diff
git add the_files_or_subdir_to_be_updated
git commit -s  # commit with your signoff,
git log # have a look at your commit log

If you found any mistakes after commit, you can revert with "git reset --soft HEAD^".

4. when you are ready, you may send your new  commit to the public server
git push

Or, you can submit the patches via e-mail , eg to nios2-dev mailing list.
git format-patch  AAAA..BBBB   # generate patches from commit AAAA to commit BBBB, output numbered patches
git send-email --smtp-server your.mail.server --to whom@where  0001-xxxx.patch

5. if you want to make a lot of changes or develop a new driver, you may create an experimental branch. You can push the branch early so that others can join the test.
git branch my_test_branch
git checkout my_test_branch
...edit,test,commit...
git push origin my_test_branch

6. You can use git-format-patch and git-am to cherry-pick and merge branches, read the man pages.

git format-patch AAAA..BBBB # generate patches from commit AAAA to commit BBBB, create numbered patches 00xxx.patch
git checkout v2.6.23-uc
git pull
git am 00xxx.patch
git log # check again
git push origin v2.6.23-uc

---

Setup a git server for public

This is how I setup the sopc git server using Debain 4.0. It should be the same for Ubuntu. It is welcome to mirror the sopc server.

Install a minimum system with netinst.iso . As root on server,

0. Add this line, for updated git packages from backports.org .
deb http://www.backports.org/debian etch-backports main contrib non-free
to your /etc/apt/sources.list.

1. apt-get install openssh-server apache2 rsync
   apt-get -t etch-backports install git-core git-daemon-run gitweb

2. edit file /etc/apache2/sites-available/gitweb, replace "example.org" with your domain name.

<VirtualHost *>
    ServerName git.example.org
    ServerAdmin webmaster@localhost
    HeaderName HEADER
    # bogus but safe DocumentRoot
    DocumentRoot /var/cache/git
    ErrorLog /var/log/apache2/gitweb-error.log
    CustomLog /var/log/apache2/gitweb-access.log combined
    Alias /robots.txt /var/www/cvs.robots.txt
    Alias /gitweb.css /var/www/gitweb.css
    Alias /git-logo.png /var/www/git-logo.png
    Alias /git-favicon.png /var/www/git-favicon.png
    Alias /git /var/cache/git
    ScriptAlias / /usr/lib/cgi-bin/gitweb.cgi
    RedirectMatch permanent "^/~(.*)$" "http://example.org/~$1"
</VirtualHost>

ln -s /etc/apache2/sites-available/gitweb /etc/apache2/sites-enabled/100-gitweb
(optionally, copy png files from git source git/gitweb to /var/www)

(optionally, make link for ssh, ln -s /var/cache/git / )

 
3. prepare for publishing, you can place the git in home or ( other shared ?) dir, eg /home/you/git/uClinux-dist.git, then add a symlink in /var/cache/git .

as a user,
cd ~
mkdir git
cd git
mkdir uClinux-dist.git
cd uClinux-dist.git
git --bare init --shared
git remote add origin git://sopc.et.ntust.edu.tw/git/uClinux-dist.git
git  --bare fetch   # to pull from server at origin, will take some time at first run

touch git-daemon-export-ok     # to enable git://
git --bare update-server-info  # to enable http://
chmod a+x hooks/post-update
edit description               # to display on gitweb

You can add a cron job to pull updates from origin daily,
cd /home/you/git/uClinux-dist.git
git --bare fetch


as root, add this link for publishing.
ln -s /home/you/git/uClinux-dist.git /var/cache/git

4. update your DNS server, resolve both names to the same ip.
git.example.org is the virtual host.
example.com is the real host.

Summary of branches on sopc server

We have bandwidth issue with our git server at NTUST. To help reduce the network loading, please don't clone directly from sopc server whenever possible.

binutils.git    binutils
These patches were merged to buildroot. You won't need to use this directly.
master : gnu binutils
nios2-buildroot : nios2 devel for buildroot
nios2 : nios2eds gnutools

boards.git    dev board projects
DE1_SD_Card_Audio : example quartus project and tryout zImage

elf2flt.git    elf2flt utility
These patches were merged to buildroot and uclinux.org CVS. You won't need to use this directly.
nios2 : nios2 devel for elf2flt
master : sync to elf2flt cvs at uclinux.org daily

gcc3.git    gcc 3.4
These patches were merged to buildroot. You won't need to use this directly.
master : gnu gcc3
nios2-buildroot : nios2 devel for buildroot
nios2 : nios2eds gnutools

insight.git    Insight GDB
v6_4_nios2 : nios2 devel for insight v6.4
master : insight
nios2-buildroot : nios2 devel for buildroot
gdb : gnu gdb
nios2 : nios2eds gnutools

linux-2.6.git    Linux kernel.
To use this git, please clone from Linus' git and fetch from sopc server. See KernelPatches.
master : sync to Linus' git daily
v2.6.23-uc : nios2 devel for v2.6.23-uc0

u-boot.git    Das U-Boot
To use this git, please clone from DENX git and fetch from sopc server.
master : sync to DENX git daily
nios2 : nios2 devel

uClinux-dist.git    uClinux distro
To use this git, please download uClinux-dist-20080131.tar and fetch from sopc server.
nios2 : nios2 devel for uClinux-dist-test (unstable)
master : nios2 devel for uClinux-dist (stable)
test : patches of uClinux-dist-test from uclinux.org

ref:

/usr/share/doc/git-core/
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#maintaining-topic-branches