Applicable Plans - All Cloud Hosting Plans

Using Git

Overview

Git is a distributed version control system (also called a source code management system), generally used by software developers to manage and track changes in source code. More information about Git can be found on the Git home page - http://git-scm.com/.

Git can be used for almost any size project, from single developers storing files on their local computer all the way up to projects like github - https://github.com/, which hosts over 3 million Git repositories. The source code for the Linux kernel, which is currently over 15 million lines of code, is managed with Git (Git was actually written just for this purpose).

There is an extraordinary amount of information available about Git on the Internet, as well as quite a few books published that cover how to use Git from both the beginner and advanced levels. If you need more information than is provided in this User Guide, you are strongly encouraged to seek out and find these other resources.

For a very detailed resource about using Git, see The Git Book, available for free directly from the Git web site - http://git-scm.com/book. Links to other Git documentation, including videos and links to books written about Git, is available here - http://git-scm.com/documentation/

What is covered in this User Guide

Installing Git

Git configuration - Virtual Server
    Create the directory for the Git repositories
    Create the user that will have access to the Git repositories
    Adding the SSH public keys

Git Quick Start
    Quick Start - Command line (Mac OS X/Linux/UNIX)
    Quick Start - Git for Windows GUI

Other Git resources
    Git usage
    Windows
    Mac OS X/Linux/UNIX

What is covered in this User Guide

Because of the wide range of possibilities available with Git, it is impossible for this user guide to cover more than just the basics.

What will be covered in this user guide is one of the more common scenarios: a Git repository hosted on a central server (your Virtual Server at eApps), being accessed by one or more developers from their local computers.

This user guide will explain how to install Git on the Virtual Server, create a user that will be used to access the Git repositories on the Virtual Server, and set up the location of the Git repos on the VS.

Also, two Quick Start guides are provided - one for using Git from the command line (Mac OS X/Linux/UNIX) and one for using the Git for Windows GUI. These Quick Start guides provide a simple overview of a common Git workflow, and are not intended as a comprehensive guide to using Git.

It is assumed that you already have Git installed on your local computer. The installation, configuration, and day to day usage of Git on your local computer is far outside the scope of this user guide. Extensive documentation exists both online and in printed form covering this topic. An Internet search for "Git install (your OS)" will generally find what you need.

If you need a more robust configuration, including more fine-grained access controls, you can look at an application like Gitolite - https://github.com/sitaramc/gitolite. The documentation for Gitolite can be found here - http://sitaramc.github.com/gitolite/master-toc.html. There are also several tutorials available online that cover installing and configuring Gitolite.

Installing Git

Installing Git using the Control Panel

Installing Git using the ISPmanager Control Panel

If you are using the ISPmanager Control Panel, you can install Git from that Control Panel.

• For ISPmanager 4, go to Server Settings > Applications. Install Git. More information on installing applications can be found here - Installing Server Applications.

• For ISPmanager 5, go to Settings > Features. Install Git. More information on installing applications can be found here - Installing Features (Server Applications).

Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions

Git configuration - Virtual Server

All of the Git configuration on the Virtual Server is done from the command line. You will need to be able to connect to the VS using SSH, and work as the root user. You will also need to be able to navigate the Linux file system, and execute basic Linux commands.

Create the directory for the Git repositories

By general convention, Git repos are in /opt/git. To create this location, connect to the VS using SSH, and if necessary switch to the root user. Change directories to /opt, and create the new directory with the mkdir git command.

This creates the directory where you will store all your Git repos. You will still need to create the git user and change the owner and group of the /opt/git directory, which is covered in the next section.

Create the user that will have access to the Git repositories

If everyone who will have read and write access to the Git repo already has SSH access to the VS, then all you will need to do is to create a new group, add those users to that group, and then change the owner and group of /opt/git so that the new group has read and write access to the repo.

However, if you do not want to give all the developers full SSH access to the Virtual Server, you can create a single user that will have access to the Git repos and nothing else. Then, all your developers can send you their SSH public keys, and you can add them to to .ssh/authorized_keys file for that user.

To add the git user, use the useradd command. This example will walk you through creating a git user, but you can use any username you wish, as long as that user name doesn't already exist. The useradd command also creates a group with the same name as the user.

This creates a /home/git directory, and uses the bash shell. The line for the git user in /etc/passwd looks like this:

At this point, change directories to /opt, and use the chown -R git:git command (note the capital R) to change the user and group of the git directory.

Now change directories to /home/git, and create a .ssh directory, and an authorized_keys file. This is the file where you will store the public SSH keys for your users. Then you will need to change the owner and group of both the directory and the file, and change the permissions on the file.

Use the mkdir .ssh command to create the directory, and the touch .ssh/authorized_keys command to create the file.

Note that the .ssh directory starts with a dot (.). This means that you will not see it using a regular directory listing command such as ls or ll, you will need to use the -a switch to see the hidden files.

Once you have created the directory and file, you will need to change the owner and group to git:git, and change the permissions on the authorized_keys file to 600.

Do this with the chown -R git:git .ssh command (note the capital R), and then change directories into .ssh and use the chmod 600 authorized_keys command.

Adding the SSH public keys

Once the git user is set up, your users will need to send you their SSH public keys, which you will need to add to the authorized_keys file in /home/git/.ssh

If your users have not created an SSH key pair (a public and private key), they will need to do so now. Make sure that they generate an RSA key. The eApps SSH User Guide has information on how to create SSH keys for both Mac OS X/Linux/UNIX and Windows.

An Internet search for "SSH key generation (your OS)" will also find quite a few tutorials on how to generate an SSH key pair.

Make sure that your users know to only send you the public key, which usually named something like id_rsa.pub. Once you have the SSH public keys, you will need to copy them to the Virtual Server, and then add them to the authorized_keys file. It is a good idea to rename the public keys before moving them to the VS, so that you don't accidentally overwrite them. Use a naming scheme like user_name.id_rsa.pub.

The best method is to use scp, either from the command line of your local computer or from an SCP client like FileZilla - http://filezilla-project.org/.

Once you have the SSH public keys on the VS, you will need to copy them into the authorized_keys file using the cat user_name.id_rsa.pub >> /home/git/.ssh/authorized_keys command. Note the two greater than signs (>>). This appends the text to the file, instead of overwriting what is already in the file.

Once you have added the public keys to the file, your users will be able to connect to the VS via SSH as the git user, without having to enter a password.

Git Quick Start

The following will walk you through creating a "bare" Git repository on your local computer, moving those files to the Git repo located on your Virtual Server, and then cloning that repo.

There are two Quick Start examples here - one using the command line on Mac OS X or Linux/UNIX, and one using the Git for Windows GUI. Both of these examples assume the following:

1. You have Git installed on your local computer
2. You have a directory containing files you want to manage with Git
3. You have uploaded your SSH public key to the git user on the Virtual Server

Please note that installing and configuring Git on your local computer is outside the scope of this user guide and outside the scope of eApps support.

Neither of these examples are meant to be a comprehensive guide to using Git, they are simply a quick overview of a common Git workflow.

Quick Start - Command line (Mac OS X/Linux/UNIX)

In this example, you have your project files in a directory on your local computer called project_folder, and will be connecting to the Git repo on eapps-example.com, as the git user. You will of course need to substitute your own project folder name and VS hostname.

Create the Git repo on the local computer

Change directories into the project directory, and run the following commands:
git init
git add *
git commit

The git commit command will open a file in your default text editor. Add a commit message like "Initial commit", and save and exit the file.

The next step is to create what is called a "bare" repository from your project files.

Change directories back to the parent directory, and run the following command: git clone --bare project_folder project_folder.git

This creates a bare repository, called project_folder.git

Move the Git repo to the Virtual Server

The next step is to use scp to copy the bare repository to the Virtual Server, as the git user. This example relies on the fact that your SSH public key is in place on the VS. If it is not, you may have to set and enter a password for the git user.

Use the command scp -r project_folder.git git@eapps-example.com:/opt/git (remember to substitute your own hostname for eapps-example.com)

What you will see will look similar to this:

This places the files in the Git repo on the Virtual Server. Now anyone who has access to the VS as the git user will be able to check out the repo, do their work, and commit their changes back to the repo.

Clone the Git repo to the local computer

To clone this repo, use the command git clone git@eapps-example.com:/opt/git/project_folder.git my_folder (where my_folder is the folder where you want to clone the repo to on your local computer)

Committing your changes back to the Git repo on the VS

Now you can do your work on the project. When you are ready to commit your changes, use the git status command to see what files need to be committed, and then the git add command to add your new files or any file changes. Then use git commit to commit the changes, and the git push command to push your changes back to the repo.

Remember, this is an example of a very simplified workflow. See the Other Git resources section of this user guide for links to more extensive documentation on using Git.

Use git status to see what changes have been made. In this example, file1.txt and file3.c have been modified, and file4.txt has been added.

Use git add to add the changed files and the new file.

The git commit command will let you commit your changes. The command will open your default text editor, and allow you to add a commit message, usually used to describe what you changed.

There are some conventions for writing Git commit messages - http://365git.tumblr.com/post/3308646748/writing-git-commit-messages that may be useful for you to follow, especially if you are working with a team of developers.

Once you have added your commit message, save and exit the file.

After the commit, you need to push the changes to the repo so that other users can have access to them. Use the git push command for this. Because you cloned the repo as the git user, Git will push the changes back to the repo as that same user. Again, this relies on the fact that your SSH key is on the VS.

Now you can keep working, and adding your changes back to the repo as needed.

Again, this is an example of a very simple workflow, and is in no way a comprehensive guide to using Git. The Other Git resources section of this user guide has links to several Git tutorials and to the official documentation.

Quick Start - Git for Windows GUI

In this example, you have your project files in a directory on your local computer called ProjectFolder, and will be connecting to the Git repo on eapps-example.com, as the git user. You will of course need to substitute your own project folder name and VS hostname.

It is also assumed that you have the Git for Windows GUI application installed. These examples use Git for Windows, which is for Git users on Windows, and not msysGit, which is generally used by Git developers on Windows. These examples also use PuTTY and Pagent to manage the SSH connection and keys. See the SSH User Guide for more information if necessary. The SSH User Guide covers basic SSH usage, and also how to create and use SSH keys in a Windows environment.

Please note that installing and configuring Git for Windows on your local computer is outside the scope of this user guide and outside the scope of eApps support.

Create the Git repo on the Virtual Server

Before you can create the repo on your local computer, you will first need to create the repo on the Virtual Server so you can upload your local repo to it. If you do not do this, you will not be able to upload your repo from your local computer to the Virtual Server.

Connect to the VS using SSH. These examples use PuTTY and Pagent. You can work as either the git user or the root user, but if you do this as the root user you will need to change the owner and group of the new repo to git:git. These examples use the git user.

Change directories to /opt/git, and use the mkdir ProjectFolder.git command to create the repo. Then change directories into the new directory, and use git --bare init to create the repository.

You can disconnect from the VS at this point. When you are ready to push your changes to the Virtual Server, you will need to reopen the connection using PuTTY and Pagent.

Create the Git repo on the local computer

Navigate to the location of the ProjectFolder folder, and right click on the folder icon. From the list, chose Git Gui

This will open the Git Gui startup screen.

Click on Create New Repository.

This will open the Create New Repository screen. Click on Browse, and navigate to the folder where you are creating the Git repo.

Once you have found the correct folder, click on Create.

This opens the main Git Gui window, which is what you will see from now on when you right click on the project folder and select Git Gui from the menu.

In order to put the ProjectFolder repo on the Virtual Server, you will need to let Git know who you are, so that any commit messages will have the correct name. From the main Git Gui window, go to Edit > Options.

This opens the Options window. Generally, all you need to change is User Name and Email Address in both the ProjectFolder Repository (the newly created repo) column and the Global (All Repositories) column.

Once you have made your changes, click Save.

Make the Initial Commit

Now you need to move the files in your repo from Unstaged to Staged, and then commit the repo. Once that is done, you will need to push the repo to the VS.

In the main Git Gui window, all your files are currently listed in the Unstaged Changes column. Click on the icon to the left of each file name, and that will move the file to the Staged Changes (Will Commit) column.

Once you have moved all the files to Staged Changes (Will Commit), enter in a commit message and click Commit.

Move the Git repo to the Virtual Server

Once you have made the initial commit, it is time to move the repo to the Virtual Server. To do this, Pagent must be running and using the SSH key for the git user. See the eApps SSH User Guide for more information if necessary.

In the main Git Gui window, go to Remote > Push. This opens the Push window.

The master branch should already be highlighted.

Under Destination Repository, click on Arbitrary Location, and enter in: user@hostname:/path/to/repo, which in this example is git@eapps-example.com:/opt/git/ProjectFolder.git

Once you have entered in the location, click on Push. This will open the status window. If the push is successful, you will see a screen similar to this.

This places the files in the Git repo on the Virtual Server. Now anyone who has access to the VS as the git user will be able to check out the repo, do their work, and commit their changes back to the repo.

Cloning the repository

To clone a repository, right click on any folder that doesn't currently contain a Git repo, and select Git Gui. This will take you to the Git Gui startup screen.

Click on Clone Existing Repository.

This opens the Clone Existing Repository screen.

• Source Location - this is where the Git repo is located. You will need to enter this in the format of user@hostname:/path/to/repo, which in this example is git@eapps-example.com:/opt/git/ProjectFolder.git.

• Target Directory - the location where you are cloning the Git repo on the local computer. This folder cannot currently exist on your computer. Browse to the parent folder where you want to clone the repo, and then add the folder name - in this example, the repo is being cloned into ProjectRepo folder in the Documents folder.

Once you have entered the information, click on Clone. A status window will appear, showing the progress. Once the clone is complete, the main Git Gui screen will appear. Note that the path at the top of the window shows the location where the repo was cloned to.

Committing Your Changes

At this point, you can do your work on the project files. In this example, you've modified file1.txt, file3.c, and added file5.txt. In order for Git Gui to see these files in the main screen, you may have to click the Rescan button. Notice that your new file and your changed files will appear in the Unstaged Changes column.

Click the icon to the left of the file name to move it from Unstaged Changes to Staged Changes (Will Commit).

Once you have moved the files to Staged Changes (Will Commit), enter a Commit Message, and click on the Commit button.

Pushing your changes to the remote repo

Once you have committed the changes, click on the Push button just below the Commit button. This will open the Push Branches screen.

Since you are pushing back to an existing repository, leave the default Destination Repository of Remote - origin as is.

Click on Push to push your changes. A status window will appear.

This shows that you have successfully pushed your changes back to the repository. You can close the window.

Now you can keep working, and adding your changes back to the repo as needed.

Again, this is an example of a very simple workflow, and is in no way a comprehensive guide to using Git. The Other Git resources section of this user guide has links to several Git tutorials and to the official documentation.

Other Git resources

For more information on Git configuration and usage, see the following. Mastering Git will require some time and effort on your part - Git is a very powerful, but also very complex application. However, most users only need to know a few commands to interact with Git on a daily basis and can look up more advanced commands as needed.

Git usage

• An in-depth guide to using Git on a central server (from the Git Book) - http://git-scm.com/book/en/Git-on-the-Server

• Git commands - http://www.kernel.org/pub/software/scm/git/docs/everyday.html

• GitGuys tutorials - http://www.gitguys.com/

• The Git Parable - http://tom.preston-werner.com/2009/05/19/the-git-parable.html

• The Git Tutorial - http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html

Windows

• Git on Windows (using Git for Windows and PuTTY) - http://nathanj.github.com/gitguide/tour.html

• Creating SSH keys using PuTTY - http://the.earth.li/~sgtatham/putty/0.62/htmldoc/Chapter8.html#pubkey

There are additional GUI clients for Windows available, but the Git on Windows client is the standard. A list of GUIs is available here - http://git-scm.com/downloads/guis

Mac OS X/Linux/UNIX

Using the Terminal in Mac OS X, or a terminal emulator (or the console) in Linux/UNIX, you can work with Git directly from the command line. See any available documentation related to using Git from the command line for more information.

There are also GUI clients for Mac OS X available, such as GitX or Tower. A list of GUIs for all platforms is here - http://git-scm.com/downloads/guis