- 1 Description
- 2 Dependencies
- 3 Creating the git repository
- 4 Moderation
- 5 How to administrate it (panel)
- 6 How to use it
- 6.1 Basic Operations
- 6.2 Using git as an anonymous user
- 6.3 Using CGit
- 6.4 Configuring SSH in GNU/Linux
- 6.5 Pushing to the Git repository on git.tuxfamily.org
- 6.6 Collaborative development, Write access
- 7 Tricks and tips
- 8 Useful links
If you only want to run git from the command line, then git is all you need to install.
But there are optional Graphical User Interfaces (GUIs) available to help you, such as:
git-gui (git gui) - Helps with staging files for commit, writing commit messages, and pushing.
gitk - Helps with reviewing the history of git commits.
Creating the git repository
- Go to the control panel
- Select the project where you want to add a git repository
- Choose the name of your repository
- Don't choose a too usual name
- Fill in the description field to avoid problems with the moderation team ;)
Your repository will be subject to moderation, see here
How to administrate it (panel)
On the panel you can choose if you want the repository to be public. By accepting it, you allow a read-only anonymous login on the repository and you allow viewing it from the gitweb.
How to handle group rights
This object can be shared with your group using the ACL
How to destroy it
- Log into the panel
- click on the group corresponding to your project
- click on your git repository
- click on destroy
How to use it
So, you've chosen to be hosted by TuxFamily, that's good. You chose a git repository, that's great ! We're going to teach you how to use it.
Start by creating a local version of your repository. We will assume that you already have a directory with your project inside.
$ cd myproject $ git init $ git add myfirstfile mysecondfile $ git remote add origin ssh://YOURUSER@git.tuxfamily.org/gitroot/YOURPROJECT/REPOSITORYNAME.git $ git commit -a $ git push origin master
This will create the first commit that will be the 'master' branch of your git repository. (When your first push is done, you use "git push" normally.)
(Of course, replace YOURUSER, YOURPROJECT and REPOSITORYNAME by the real values...)
With git 1.6.2+, you can clone an empty repo:
It'll complain, but it works.
To download a full copy of your git repository, you can use the clone command:
$ git clone ssh://YOURUSER@git.tuxfamily.org/gitroot/YOURPROJECT/REPOSITORYNAME.git remote: Generating pack... remote: Done counting 6 objects. remote: Deltifying 6 objects... remote: (6/6) done remote: Total 6 (delta 0), reused 0 (delta 0) Indexing 6 objects... 100% (6/6) done
Adding, removing files, updating your repository
Go into your local repository
$ cd repos
let's create a file named 'file'
$ touch file
Then to add the file to your repository, just type :
$ git add file
Now, you can commit by typing :
$ git commit file
Once the commit is done, you can push everything on the server :
$ git push
For directories, we will do the same
$ git add directory/ $ git commit directory/ $ git push
Removing a file
To remove a file, just type :
$ git rm file $ git commit $ git push
Updating your local copy of the repository
When working in a team, it can be useful to update the local copy of your repository :
$ git pull Warning: You might have to type the password several times
Using git as an anonymous user
You can use git without logging in. You won't be able to change the repository (add or remove files). To make an anonymous checkout, type this :
Anonymous people can also check for updates by typing :
$ git pull
The anonymous mode is set on the panel (default=allowed)
You can see your all the public repositories here : http://git.tuxfamily.org URLs will look like this : http://git.tuxfamily.org/group/repository.git/ ( http://git.tuxfamily.org/tftest/testgit.git/ for example )
How to keep in touch with your repository
It is possible to monitor branches in your repository using CGit's Atom feed.
( http://git.tuxfamily.org/tftest/testgit.git/atom/?h=master for example )
Or monitor all branches.
( http://git.tuxfamily.org/tftest/testgit.git/atom/?all=1 for example )
Configuring SSH in GNU/Linux
TuxFamily uses Git in conjunction with SSH. This means that every time you access your repository with Git, you will have to type in your TuxFamily password to authenticate. This can become quite annoying and cumbersome.
It is possible to use SSH keys in conjunction with software like ssh-agent and keychain to provide a much more comfortable user experience, without sacrificing security.
Creating and uploading the SSH key
To use an SSH key, first of all you have to create such key. To create an SSH key open a console an type:
$ ssh-keygen -t rsa
You will be asked to type a passphrase. Once you have entered your passphrase, the key is ready to be used.
A pair of keys has been generated with the above command: your private key, which you must keep secret for yourself, and your public key, which we are going to upload to TuxFamily's server.
Your public key is named id_rsa.pub and it is placed, on creation, in your home directory under the ".ssh" subdirectory. With the following command we will copy your public key into a file called "ssh_keys" in your home directory:
$ cat ~/.ssh/id_rsa.pub >> ~/ssh_keys
Next we have to fix the permission on this copy of the public key, which will be uploaded to TuxFamily's server:
$ chmod 700 ~/ssh_keys
Finally, you will have to upload the "ssh_keys" file to TuxFamily's server using FTP. You can use any FTP client. The name of the FTP server is ftp://ftp.tuxfamily.org/ (you will have to enter your TuxFamily username and password). The "ssh_keys" file must be placed inside the root directory, i.e., the directory you will find yourself in after you connect to the FTP server.
So far we have not improved the situation very much, since, instead of TuxFamily's password, your key's passphrase will be asked each time you use Git.
Fortunately there are programs which allow you to manage your SSH keys, so that you will have to type your passphrase just once per session (or, in case of keychain, just once per boot).
The first option is to use ssh-agent.
This uses 2 commands, but first you must kill any existing agents:
Now you may run these commands to start a new agent and register the SSH key with the agent.
$ ssh-agent $SHELL $ ssh-add ~/.ssh/id_rsa
To make this happen automatically when you start a shell:
if [ -f .ssh-agent ]; then .ssh-agent else killall ssh-agent ssh-agent > .ssh-agent ssh-add ~/.ssh/id_rsa fi
Keychain is a SSH key manager that lets you load your SSH keys once per machine boot (i.e., keychain will not exit when you logout, it will sit silently in the background). Keychain uses ssh-agent internally.
Using keychain is a two stage process. First you start it, telling it to load your public key into memory:
$ keychain ~/.ssh/id_rsa
You will have to type in your key's passphrase. Then you have to read some environmental variables from a file. You can do this with the command
$ source ~/.keychain/`hostname`-sh
While you have to start keychain only once per machine boot, you will have to read the environmental variables each time you start a console session. To avoid this step, you can add something like this at the end of your ".bashrc" file (assuming you are using the bash shell):
if [[ $- != *i* ]] ; then # Shell is non-interactive. Be done now! return else keychain --nolock ~/.ssh/id_rsa source ~/.keychain/`hostname`-sh fi
In case you are wondering, the "if" statement makes sure you are in an interactive shell before launching keychain and reading the environment variables.
Please refer to the keychain homepage for more documentation.
Pushing to the Git repository on git.tuxfamily.org
You can access it by ssh but not by the git protocol (git://):
$ git push ssh://'USERfirstname.lastname@example.org/gitroot/'PROJECT'/'REPOSITORY'.git master
git config of the tuxfamily's repository
The git-config's options receive.denyDeleteCurrent and receive.denyNonFastForwards seem to be set, so you will not be able to delete anything from the branch 'master'. It is however still possible to delete other branches or tags:
$ git push ssh://'USERemail@example.com/gitroot/'PROJECT'/'REPOSITORY'.git "":devel
If you want to delete from the master branch once (for example because of a mistake), you can make sure that you have a backup of the repo, then delete it, wait for the deletion to be effective, recreate it and finally push the backup to it (without the unwanted commits of course). If you would like to regularly rebase or delete the branch 'master' you can contact an admin so that it can disable these options on your repository or, better still, implement a configuration of this option through the panel in VHFFS (see https://www.vhffs.org/dev:mainpage).
Collaborative development, Write access
All users group will have permission to write to the git. In other words, if you want to develop more on a single repository, it is advisable to add developers to the group through the panel. However, it is necessary that developers create an account on the first panel.
A project is a group (within the meaning of the word Unix), add your co-developers to your project so they can commit on changes to the git repository.
Otherwise, you may get an error message similar to the following:
error: unable to create temporary sha1 filename ./objects/tmp_obj_9tDId6: Permission denied fatal: failed to write object unpack unpacker exited with error code ng refs/heads/master n/a (unpacker error) error: failed to push to 'ssh://firstname.lastname@example.org/gitroot/yyy/zzz.git'
Tricks and tips
- We recommend committing only code that compiles correctly (even if it doesn't work completely) to always be sure that the repo can be used by new users at any time.
- You have to choose the files you want to put on your git repository. It is not necessary to upload backup files, or binary files. Be careful, some text editors make automatic backups in xxx~.
- Please don't choose a generic name for your repository such as "git". Instead, choose an intelligent name or in the worse case, use your project name...