Menu ▾ ▴

Git

There is a newer version of this page. You can find it here.

What is Git?

Git is a Source Code Management (SCM), a tool for software developers which supports collaborative development of software within a team, and the tracking of changes to software source code over time.

Git is used by developers, and advanced users who need the very latest changes to the software (before releases occur). Software users generally do not need Git; typically they will download official file releases made available by the project instead.

Developers should familiarize themselves with Git by reading the Git Documentation.

Modern SCM facilities

Here's a nice writeup of why you should consider using a Distributed Version Control System (DVCS), and a comparison of the major DVCSs: http://www.infoq.com/articles/dvcs-guide

Features

SourceForge.net provides the following features in its Git offering:

  • All 1.6.x features of git are supported.
  • Developer (read/write) access is provided via ssh.
  • anonymous (read-only) access are provided via git's daemon protocol ("git://").
  • Several Git clients are supported, including:
  • The official git client (MS Windows, Mac OS X, Linux, BSD).
  • Repositories may be viewed via web browser using the GitWeb.
  • Existing repositories may be imported via a normal git push (since git is a distributed SCM).
  • Repository access may be granted or revoked from a developer using the Project Admin interface.
  • Repository backups and mirroring may be performed using rsync or git clone.
  • Service usage is not restricted by quotas.
  • Multiple repositories are supported.

Management

Git service may be enabled for your project as follows:

  1. Login as a project administrator and click on the Admin icon in the navigation bar.
  2. Click on Tools.
  3. Click to enable Git.

Once Git has been enabled, you may wish to adjust permission grants for your users, if you need to disable one or more user's ability to make changes in the git repository.

The standard way to modify the contents of your repository is using a Git client as detailed in the Git User's Manual. Refer to the Getting Started section for how to make your first commit to your new repository.

Administrators may also manually manipulate their repository via the site interactive shell service.

We strongly recommend that when modifying a repository, other committers be notified of the direct edit window and that you make your own backups prior to editing the content so you can restore it readily yourself in the case of an accident.

Access

To access a Git repository, configure your Git client as follows (replace PROJECTNAME with the UNIX group name of the project, and REPONAME with the name of the git repository):

git://PROJECTNAME.git.sourceforge.net/gitroot/PROJECTNAME/REPONAME (read-only)
ssh://USERNAME@PROJECTNAME.git.sourceforge.net/gitroot/PROJECTNAME/REPONAME (read/write)

The default repository name is the same as the project's UNIX group name, e.g

git://PROJECTNAME.git.sourceforge.net/gitroot/PROJECTNAME/PROJECTNAME

For those developers who have git access enabled to more than 16 projects, you may need to include your PROJECTNAME as a part of the USERNAME (appended after a comma) in order to work around a Linux permission limitation:

ssh://USERNAME,PROJECTNAME@PROJECTNAME.git.sourceforge.net/gitroot/PROJECTNAME/REPONAME (read/write)

Authentication

The read-only access does not prompt for a password.

The read/write access uses your ssh password or ssh key to authorize your access. To perform write operations, your project administrator must have granted you write access to the repository.

Getting Started

Note: - For all examples below, "PROJECTNAME" represents a SourceForge.net project UNIX name and "USERNAME" represents your SourceForge.net user account.

Your project's Git repository will be completely empty at the start. If you have a local Git version older than 1.6.2, you won't be able to clone (pull) your remote repository while it is empty, so see below for how to set up a local repository to push your content to our servers.

How to create a new local repository

Create an empty repository on your local machine like this:

mkdir PROJECTNAME
cd PROJECTNAME
git init

How to clone an existing repository

For a newer version of git (1.6.2 and later), you can simply clone your empty remote repository and get working:

git clone ssh://USERNAME@PROJECTNAME.git.sourceforge.net/gitroot/PROJECTNAME/REPONAME

cd REPONAME
The first time you try connecting to the PROJECTNAME.git.sourceforge.net host, you should see a message similar to the following:

The authenticity of host 'PROJECTNAME.git.sourceforge.net (216.34.181.91)' can't be established.
RSA key fingerprint is 86:7b:1b:12:85:35:8a:b7:98:b6:d2:97:5e:96:58:1d.
Are you sure you want to continue connecting (yes/no)?

Before typing 'yes' to accept the host fingerprint, ensure the fingerprint is correct for the host. You can find a listing of SSH host keys in the SSH Host Key Fingerprints list. If you receive a host key warning, please contact the SourceForge.net team.

Setting your git username

Users should commit to their project repository using their SourceForge.net username. If that is not already set globally, you can set it locally for the current Git repository like this:

git config user.name "YOUR NAME"
git config user.email "USERNAME@users.sourceforge.net"

You can now use some combination of "git add" and "git commit" commands to create one or more commits in your local repository.

How to push a local repository

If you did not clone one of our remote repositories (for instance, if your older git version won't let you clone an empty repository), you will have to take some manual setup steps to be able to push your content to our servers.

For any local Git repository, you can configure it to push data back to our server by doing the following from inside your Git repository (this replicates what a "git clone" from our servers sets up for you automatically):

git remote add origin                 
ssh://USERNAME@PROJECTNAME.git.sourceforge.net/gitroot/PROJECTNAME/REPONAME
git config branch.master.remote origin
git config branch.master.merge refs/heads/master

Now you're ready to push the committed files to our servers:

git push origin master

Note: The use of "origin master" prevents Git from complaining that the remote server has no branches in common with your local repository (which is true at the start when the remote repository is completely empty), and "master" is the default branch in Git.

After the first push, you will be able to use the simpler "git push" to push the master branch to our "origin" server.

Once that is done, you will be able to browse your newly-committed content via gitweb, clone the repository via either read-only or read/write access methods, push more check-ins, etc.

Commit email hook setup

You can get the default post-receive-email script provided with Git and save it as "post-receive" in the hooks directory. Be sure to test this configuration for the expected result.

This script is available from http://git.kernel.org/. We have posted a copy, Git hook script example here for reference.

Restricting Access

You can add the following pre-commit hook to further restrict access to your repository

1
2
3
4
5
6
#!/bin/sh
if [ $USER != "git-repo-admin" ];
then
  echo "Manual pushing to this repo is disabled."
  exit 1
fi

Creating Multiple Repositories

To create a new repository, you need to access the Shell service, then follow these steps:

Navigate to your repository
cd /home/scm_git/P/PR/PROJECTUNIXNAME

PROJECTUNIXNAME is the UNIX name of your project
P represents the first letter of that name, and PR the first two letters of the name.
Create a new directory with the name you want for the repository, eg mkdir DIRNAME.

Run git --git-dir=DIRNAME init --shared=all --bare (where DIRNAME represents the name of the repository to be created)
This will initialize a new repository at that directory

Notes: Developers should not nest directories / repositories. Directories should only be created the top level directory of repository. Be sure to make backups prior to editing your repository contents.

Backups

SourceForge.net performs routine backups for all of our servers and will restore from these backups in the event of catastrophic server failure. We encourage projects to make their own backups of Git data as that data restore can be performed by the project in the event of accidental data destruction by a member of the project team.

Backups of a Git repository may be made using rsync.

Example (replace PROJECTNAME with the UNIX group name of your project):

rsync -av PROJECTNAME.git.sourceforge.net::gitroot/PROJECTNAME/* .

Using rsync is important if repository-side configuration such as hook scripts, a 'description' file, and a non-default 'config' file are used.