Git for Virtual Access

Introduction

This document may appear to be long, but it contains a complete script of how to set up and use Git. It won’t take long to read, but I hope it will help you understand the basics of what CVS does, as well as how to set it up and use it.

Git is a distributed version control system. It is a uniquely powerful tool for managing source code that is being developed by multiple programmers at multiple locations. It automatically takes care of keeping a history of every version of the code, merging changes made by different programmers, remembering exactly which version of each source file went to make up a release, and applying bug fixes made to earlier releases to the current development code.

Git differs from CVS in that each developer manages a local copy of the whole repository. Each developer can work on bug fixes and new features and manage them within the local repository, and when a piece of work is complete can "push" the changes to the parent repository. This is unlike CVS which has only a central repository held on the server.

That parent repository of all versions of the code is kept on the SourceForge server, and can be read by anyone using anonymous CVS access, and updated by any authorised person using SSH access.

Many people use the commandline git program to do this, but various GUI front-ends are available. We use the Tortoise Git front-end, which integrates with Windows Explorer. This simplifies the process of managing communications securely with the Sourceforge server using SSH.

Developers use the Git client on their machine to "clone" the repository from the central server. This sets up the local repository and, by default, also fills the workspace with working copies of the current versions of all the files.

The local repository can be updated with changes made by other developers by "pulling" them fron the central server (to which the other developers have "pushed" them). This can be done at any time, and should always be done before a "push" as it may lead to conflicts that need to be resolved manually. Git provides tools to help with the merging of versions that is needed when a conflict occurs.

When code is released, a tag is added to the central repository. This marks the current version of each file with a name, which can then be used later to retrieve that exact same set of source files (e.g. for bug fixing).

Installing git

Git itself can be downloaded from the Git website. Download the Windows version of the client software, which is known as "Git for Windows" or as "msysGit" (because it is the version of Git that can be used with the MSYS Linux-like environment under Windows).

Tortoise Git can be downloaded from the Tortoise Git website. The link to msysGit on that site downloads the same Git version that you would get from the Git website.

Now that you have Git you can use it to clone the VAOS repository. Instructions are given below, and more information is available direct from SourceForge Here.

Getting anonymous (read-only) access to the virtual-access Git repository on SourceForge

If you only want to read the VAOS source or to build your own copy of VAOS this is all you need to do. This will not allow you to puch changes back to the central repository, though.

Once you have git it is easy to clone the VAOS repository. The URL is given on the Virtual-Access page on Sourceforge here.

You will want to set up a working space for your Git VAOS repository. To do this create a new directory – let's call it "Workspace" – and change to it.

 mkdir Workspace
 cd Workspace

Using the commandline given on that page you can create a clone like this:

 git clone git://git.code.sf.net/p/virtual-access/VAOS6 virtual-access-VAOS6

If you do this from your Workspace directory the command will create a clone of the VAOS repository in Workspace\virtual-access-VAOS6 (you may want to pick a shorter subdireectory name). That's all there is to it.

You can achieve the same thing using Tortoise Git by opening the Workspace directory in Windows Explorer, right-clicking on the empty directory pane, and selecting "Git clone ...".

Getting read-write access to the virtual-access Git repository on SourceForge

In order to get read-write access, you first have to have a SourceForge login id, and you then have to persuade the Virtual Access Foundation to give you read-write permission. If you already have access to the Sourceforge CVS repository you can use exactly the same credentials and keys.

Then you need to install an SSH client. We recommend PuTTY. Tortoise Git ships with a subset of PuTTY that is sufficient for its use. If you want to use Git from the commandline you will need the full product, as the PuTTY ssh client plink.exe is not included in the PuTTY subset shipped with Tortoise Git. The full product is available from here. If you have previously used the Sourceforge CVS archive you will probably already have PuTTY.

You will need a public/private key pair to authenticate your connections to the Sourceforge server. You can use the same keys for Git as you may already have used with CVS, but if you are new to this you will need to generate a key pair. To do this run PuTTYgen. You want to generate a SSH2 RSA key. Set the key comment to <your user name>@<your machine name> (e.g. [nikki@trumphurst.com-mailto:nikki@trumphurst.com]). Select all the text in the Public key for pasting box, and copy it to the clipboard (with ^C). Save the private key to C:Program FilesPuTTY, naming it id_rsa.PPK.

Start a text editor; paste your saved public key into it, and save it as C:\Program Files\PuTTY\authorized_keys.

Now you need to register your public key with the SourceForge server. Click "my sf.net", and choose the "Account Options" page. Scroll down to "Host Access Information", and click "Edit Keys". Paste your public key into the text box, and press the Update button. Note that the key may take up to 24 hours to register with SourceForge. Access via ssh will not work until then.

Now we need to tell PuTTY where we put the key file. Start PuTTY. On the configuration screen, click the SSH radio button. Move to the SSH page, and ensure Preferred SSH protocol version is set to 2. Move to the SSH/Auth page, and browse to your id_rsa.PPK public key file (in C:Program FilesPuTTY). Return to the Session page, Click Default Settings, then press the Save button.

To use the key you need to run the Pageant program (part of the puTTY suite). When you run Pageant it creates a system tray icon (a computer wearing a hat), right-click this icon and select "Add key". Select the id_rsa.ppk key that you created above, and type in the passphrase. Pageant keeps the key in memory so that puTTY can find it when it needs it.

You will want to set up a working space for your Git VAOS repository. To do this create a new directory – let's call it "Workspace" – and change to it.

 mkdir Workspace
 cd Workspace

You should use a clean Workspace directory for this. I haven't tried making a read-write clone on top of a read-only one so don't assume that will just work.

Now clone the repository. The normal way to do this on a Unix-like system is to use the secure shell (ssh) command, and this method is supported on Windows by puTTY.

You need to set two environment variables:

 set GIT_SSH=C:\Program Files\Putty\bin\plink.exe
 set PLINK_PROTOCOL=ssh

The lines above will set the variables correctly for the current console session, if you intend to use Git from the commandline on a regular basis you should set these permanently in one of the usual ways.

You then need to run plink interactively to get the remote server's key fingerprint and accept it into your local store. The purpose of the fingerprint is to identify the remote server and ensure that you only connect to the genuine Sourceforge server. You should check the fingerprint reported against the one advertised by Sourceforge and refuse the connection if it differs.

The correct sourceforge key fingerprints are shown Here (but note that that's not a secure web page, so you shouldn't really trust that, either).

 C:\Workspace>plink -ssh git.code.sf.net
 The server's host key is not cached in the registry. You
 have no guarantee that the server is the computer you
 think it is.
 The server's rsa2 key fingerprint is:
 ssh-rsa 2048 86:7b:1b:12:85:35:8a:b7:98:b6:d2:97:5e:96:58:1d
 If you trust this host, enter "y" to add the key to
 PuTTY's cache and carry on connecting.
 If you want to carry on connecting just once, without
 adding the key to the cache, enter "n".
 If you do not trust this host, press Return to abandon the
 connection.
 Store key in cache? (y/n) y
 login as:

Once the key is stored in the cache you can break out of the interactive session with Ctrl+C.

You are now ready to clone the repository, like this (using your own Sourceforge username, of course):

 C:\Workspace>git clone ssh://username@git.code.sf.net/p/virtual-access/VAOS6 VAOS6
 Cloning into 'VAOS6'...
 remote: Counting objects: 8316, done.
 remote: Compressing objects: 100% (2237/2237), done.
 remote: Total 8316 (delta 6278), reused 7778 (delta 5851)
 Receiving objects: 100% (8316/8316), 3.80 MiB | 62.00 KiB/s, done.
 Resolving deltas: 100% (6278/6278), done.
 Checking connectivity... done.
 Checking out files: 100% (1314/1314), done.

Git uses the GIT_SSH environment variable to find the plink program to run to implement the secure shell. Plink uses the key stored by pageant to secure the connection, and the session information stored when running plink interactively to verify the remote server fingerprint. The whole repository is cloned into the current directory (here C:\Workspace) and a working set of files is created in the VAOS6 subdirectory.

It's much easier, though, just to let Tortoise do it for you. Open the Workspace directory in Windows Explorer and right-click on the empty directory pane. Chose "Git clone ..." and select the repository and workspace (sub)directory that you want to use.

You should see progress messages in the bottom window, and Git should clone the full repository and check out working files into the subdirectory you specified.

Now that you have a local Git repository you can configure. In particular it is a good idea to set the user name and EMail address for the local repository, so that any check-ins can be identified.

 C:\Workspace>git config user.name "YOUR NAME"
 C:\Workspace>git config user.email "USERNAME@users.sourceforge.net"
 
devinfo/githowto.txt · Last modified: 03.01.2015 18:28 by daniel
 
Recent changes RSS feed Driven by DokuWiki