Git

Git is an open source distributed version control system.

The git command-line interface is installed on every WebFaction server in the /usr/bin/ directory. By default, git will be in your PATH. To see a complete list of commands during an SSH session, enter git help and press Enter.

The Git web application makes it easy to serve multiple Git repositories from your account. With the Git web application, you can clone, push, and pull over HTTP. You can also view repositories with a web browser.

See also

Bazaar, Mercurial

Installing the Git Web Application

To install a Git application:

  1. Log in to the control panel.

  2. Click Domains / websites ‣ Applications. The list of applications appears.

  3. Click the Add new application button. The Create a new application form appears.

  4. In the Name field, enter a name for the Git application.

  5. In the App category menu, click to select Git.

  6. In the Extra info field, enter a password for the default user.

    See also

    See Strengthening Passwords for important information about choosing passwords.

  7. Click the Save button.

The Git application is installed and added to the list of applications. To make your Git application’s repositories available on the Web, add the Git application to a website record.

The Git application creates a directory, ~/webapps/git, where git is the name of the application. The Git application directory contains:

  • the CGI scripts that serve your repositories,
  • .htaccess and .htpasswd files, which determine how and to whom your Git repositories are served,
  • a subdirectory, repos, to store your Git repositories, and
  • an example repository, in the repos/proj.git subdirectory.

Creating a New Repository

To create a new repository:

  1. Open an SSH session to your account.

  2. Switch to the Git application’s repos subdirectory, where your repositories are stored. Enter cd ~/webapps/git/repos, where git is the name of the Git application as it appears on the control panel, and press Enter.

  3. Create the repository. Enter git init --bare {repo}.git, where repo is the name of the new repository, and press Enter.

    Note

    The .git extension for the new repository is required. Additionally, the rest of the repository name must not contain any dots. For example, myrepo.git is acceptable, while myrepo.com.git is not.

  4. Switch to the new repository’s directory. Enter cd repo.git and press Enter.

  5. Enable HTTP push. Enter git config http.receivepack true and press Enter.

Cloning a Repository Hosted on Your WebFaction Server

You can clone a Git repository locally, over HTTP (anonymous or authenticated), and over SSH. All Git clone commands follow the same general formula: git clone remote, where remote is a path to a Git repository (for local repositories), a URL to a Git repository (for HTTP connections) or an scp-like reference to a repository (for SSH connections). Git commands issued over SSH also respect key-based authentication.

For example:

Type Git Command
Local git clone /home/username/webapps/app/repos/proj.git
HTTP (Anon) git clone http://domain/URL_path/proj.git
HTTP (Auth) git clone http://git_user@domain/URL_path/proj.git
SSH git clone username@username.webfactional.com:/home/username/webapps/app/repos/proj.git

where:

  • app is the name of the Git application as it appears on the WebFaction control panel,

  • proj is the name of the Git repository,

  • domain is the domain name where the Git application is available, as configured in a website record on the WebFaction control panel (for example, git.example.com),

  • URL_path is the URL path (or URL mount point) where the Git application is available, as configured in a website record on the WebFaction control panel,

  • git_user is a valid user as configured in the Git application’s .htpasswd file,

    See also

    Managing Users

  • and username is your WebFaction username.

Finally, for most repositories—especially if you anticipate adding large files, numerous files, or making many changes to your repository between pushes and pulls—you should change the postBuffer setting on your local repository clone:

  1. Switch to the local repository directory. Enter cd path, where path is the path to the repository, and press Enter.

  2. Enter git config http.postBuffer bytes, where bytes is the maximum number of bytes permitted, and press Enter.

    For example, to permit pushes up to 500 megabytes, enter git config http.postBuffer 524288000 and press Enter.

Enabling Anonymous Read Access

Warning

Permissions apply to all repositories within a Git application. To split permissions across different sets of repositories, create additional Git applications.

To permit anonymous users to view and clone your repositories:

  1. Open an SSH session to your account.

  2. Open ~/webapps/git/.htaccess, where git is the name of the Git application, in a text editor.

  3. Comment out these lines with a # character:

    AuthName "Git Authentication"
    AuthType Basic
    Require valid-user
    AuthUserFile /home/<username>/webapps/<git>/.htpasswd

    such that it looks like this:

    # AuthName "Git Authentication"
    # AuthType Basic
    # Require valid-user
    # AuthUserFile /home/<username>/webapps/<git>/.htpasswd
    
  4. Save and close the file.

Managing Users

When you create a Git application, the application starts with a single user: your WebFaction control panel user name. You can manage users with the htpasswd utility and the .htpasswd file.

Add a User or Change a Password

To add a new user or modify an existing user’s password:

  1. Open an SSH session to your account.

  2. Switch to the Git application directory. Enter cd ~/webapps/git, where git is the name of the Git application, and press Enter.

  3. Enter htpasswd .htpasswd user, where user is a new or existing username, and press Enter.

  4. Complete the password prompts.

    See also

    See Strengthening Passwords for important information about choosing passwords.

Delete a User

  1. Open an SSH session to your account.
  2. Open ~/webapps/git/.htpasswd, where git is the name of the git application, in a text editor.
  3. Delete the line containing the username you want to remove.
  4. Save and close the file.

Removing a Repository

Warning

Removing a repository cannot be undone.

To remove a repository:

  1. Open an SSH session.
  2. Delete the repository. Enter rm -r ~/webapps/git/repos/repo.git, where git is the name of the Git application and repo is the name of the repository, and press Enter.

Using HTTPS

If you’re using Git with a domain that already has a valid security certificate set up and you’ve configured the Git application on a website record with HTTPS enabled, just use the HTTPS protocol (https://) with Git URLs.

You can also use WebFaction’s security certificate by disabling Git’s SSL certificate verification. While cloning, use the GIT_SSL_NO_VERIFY environment variable. For example:

export GIT_SSL_NO_VERIFY=true
git clone https://demo@demo.webfactional.com/proj.git myproj

Then, disable SSL certificate verification for the repository to enable push and pull operations:

# switch to the repository directory
git config http.sslVerify false

Troubleshooting

Error: RPC failed; result=22, HTTP code = 411

If you attempt to push a large set of changes to a Git repository with HTTP or HTTPS, you may get an error message such as error: RPC failed; result=22, HTTP code = 411. This is caused by a Git configuration default which limits certain HTTP operations to 1 megabyte. To override this limitation, update the postBuffer setting on your cloned repository.