Merge lp:~tribaal/serverguide/add-git-to-vcs into lp:~ubuntu-core-doc/serverguide/saucy

[Chris Glass]

This branch adds a git section to the serverguide.

This branch adds a git section to the serverguide.

Furthermore, it adds instructions to install, configure and use "gitolite", a git server that handles advanced features like multi-tenants and access rights in a more complete and convenient way than using the bare git program with shell users.

Please review carefully.

[Doug Smythies (dsmythies)]

Hi Chris, Thanks for your contribution with this.

It does not pass validation. Please review the validation step 4 under "kickstart" on the serverguide wiki page. I did not look into why it does not pass.

review: Needs Fixing

[lp:~tribaal/serverguide/add-git-to-vcs]

145. By Chris Glass on 2013-06-11

Fixed dumb typo and forgotten para

[Chris Glass (tribaal)]

Should pass now - at least to the same extent than other sections: it seems the validation script does not like cross-references.

[Doug Smythies (dsmythies)]

I see that the references section is inconsistent with other reference sections, but I see it has been like that for a long time. We could look at that sometime later, if desired.

It all looks good to me, but I am not an expert on git.
Peter: Do you want to have a look, or should I go ahead and merge it?

Side note: I got the bzr branch I was originally using completely messed up trying to update to Chris' version 145, and I had to start again from a fresh branch. Can anybody tell me the way to properly include the 145 revision when I am already at the 144 revision (uncommitted)?

review: Approve

[Doug Smythies (dsmythies)]

I made the references consistent with other chapters.

review: Approve

=== modified file 'serverguide/C/vcs.xml'
--- serverguide/C/vcs.xml	2013-06-09 21:35:25 +0000
+++ serverguide/C/vcs.xml	2013-06-11 15:22:08 +0000
@@ -75,6 +75,133 @@
             http://bazaar-vcs.org/LaunchpadIntegration</ulink>.</para>
         </sect2>
       </sect1>
+
+      <sect1 id="git" status="review">
+        <title>Git</title>
+
+        <para>Git is an open source distributed version control system originally developped by Linus Torvalds to support the development of the linux kernel.  
+            Every Git working directory is a full-fledged repository with complete history and full version tracking capabilities, 
+            not dependent on network access or a central server.</para>
+
+        <sect2 id="git-installation" status="review">
+            <title>Installation</title>
+            <para>
+            The <application>git</application> version control system is installed with the following command
+            </para>
+<screen>
+<command>sudo apt-get install git-core</command>
+</screen>
+        </sect2>
+        <sect2 id="git-configuration" status="review">
+            <title>Configuration</title>
+            <para>Every git user should first introduce herself to git, by running these two commands:</para>
+<screen>
+<command>git config --global user.email "[e-mail]"</command>
+<command>git config --global user.name "Your Name"</command>
+</screen>
+        </sect2>
+        <sect2 id="git-usage" status="review">
+            <title>Basic usage</title>
+            <para>The above is already sufficient to use git in a distributed and secure way, provided users have access to the machine assuming the server role via SSH.  On
+                the server machine, creating a new repository can be done with</para>
+<screen>
+<command>git init --bare /path/to/repository</command>
+</screen>
+<note><para>This creates a bare repository, that cannot be used to edit files directly. If you would rather have a working copy of the contents of the repository on the server, ommit the <emphasis>--bare</emphasis> option.</para></note>
+            <para>Any client with ssh access to the machine can from then on clone the repository with</para>
+<screen>
+<command>git clone username@hostname:/path/to/repository</command>
+</screen>
+            <para>
+                Once cloned to the client's machine, the client can edit files, then commit and share them with:
+            </para>
+<screen>
+<command>cd /path/to/repository</command>
+<command>#(edit some files</command>
+<command>git commit -a # Commit all changes to the local version of the repository</command>
+<command>git push origin master # Push changes to the server's version of the repository</command>
+</screen>
+
+        </sect2>
+        <sect2 id="git-installing-gitolite" status="review">
+            <title>Installing a gitolite server</title>
+            <para>
+                While the above is sufficient to create, clone and edit repositories, users wanting to install git on a server will most likely want to have git work like a more
+                traditional source control management server, with multiple users and access rights management.  
+                The suggested solution is to install <application>gitolite</application> with the following command:
+            </para>
+<screen>
+<command>sudo apt-get install gitolite</command>
+</screen>
+        
+        </sect2>
+        <sect2 id="git-configuring-gitolite" status="review">
+        <title>Gitolite configuration</title>
+        <para>
+            Configuration of the <application>gitolite</application> server is a little different that most other servers on Unix-like systems.  
+            Instead of the traditional configuration files in /etc/, gitolite stores its configuration in a git repository. 
+            The first step to configuring a new installation is therefore to allow access to the configuration repository.
+        </para>
+        <para>
+        First of all, let's create a user for gitolite to be accessed as.
+        </para>
+<screen>
+<command>sudo adduser --system --shell /bin/bash --group --disabled-password --home /home/git git</command>
+</screen>
+        <para>
+        Now we want to let gitolite know about the repository administrator's public SSH key. This assumes that the current user is the repository administrator.
+        </para>        
+<screen>
+<command>cp ~/.ssh/id_rsa.pub /tmp/$(whoami).pub</command>
+</screen>
+        <para>
+        Let's switch to the git user and import the administrator's key into gitolite.
+        </para>
+<screen>
+<command>sudo su - git</command>
+<command>gl-setup /tmp/*.pub</command>
+</screen>        
+        <para>
+        Gitolite will allow you to make initial changes to its configuration file during the setup process. You can now clone and modify the gitolite configuration repository from your administrator user (the user whose public SSH key you imported). Switch back to that user, then clone the configuration repository:
+        </para>
+<screen>
+<command>exit</command>
+<command>git clone git@$IP_ADDRESS:gitolite-admin.git</command>
+<command>cd gitolite-admin</command>
+</screen>
+        <para>The gitolite-admin contains to subdirectories, "conf" and "keydir". The configuration files are in the conf dir, and the keydir directory contains the list of user's public SSH keys.</para>
+        </sect2>
+        <sect2 id="git-gitolite-management" status="review">
+            <title>Managing gitolite users and repositories</title>
+            <para>Adding new users to gitolite is simple: just obtain their public SSH key and add it to the keydir directory as $DESIRED_USER_NAME.pub. Note that the the gitolite usernames don't have to match the system usernames - they are only used in the gitolite configuration file to manage access control. Similarly, users are deleted by deleting their public key file. After each change, do not forget to commit the changes to git, and push the changes back to the server with</para>
+<screen>
+<command>git commit -a</command>
+<command>git push origin master</command>
+</screen>
+            <para>Reporitories are managed by editing the conf/gitolite.conf file. The syntax is space separated, and simply specifies the list of repositories followed by some access rules. The following is a default example</para>            
+<programlisting>
+repo    gitolite-admin
+        RW+     =   admin
+        R       =   alice
+
+repo    project1
+        RW+     =   alice
+        RW      =   bob
+        R       =   denise
+</programlisting>   
+        </sect2>
+        <sect2 id="git-gitolite-usage" status="review">
+            <title>Using your server</title>
+            <para>To use the newly created server, users have to have the gitolite admin import their public key into the gitolite configuration repository, they can then access any project they have access to with the following command:</para>
+<screen>
+<command>git clone git@$SERVER_IP:$PROJECT_NAME.git</command>
+</screen>
+            <para>Or add the server's project as a remote for an existing git repostory:</para>
+<screen>
+<command>git remote add gitolite git@$SERVER_IP:$PROJECT_NAME.git</command>
+</screen>
+        </sect2>
+      </sect1>
       <sect1 id="subversion" status="review">
         <title>Subversion</title>
           <para>
@@ -403,7 +530,9 @@
       <sect1 id="version-control-ref" status="review">
         <title>References</title> 
 				<para><ulink url="http://bazaar.canonical.com/en/">Bazaar Home Page</ulink></para>
-				<para><ulink url="https://launchpad.net/">Launchpad</ulink></para>
+                <para><ulink url="https://launchpad.net/">Launchpad</ulink></para>
+                <para><ulink url="http://git-scm.com">Git homepage</ulink></para>
+                <para><ulink url="https://github.com/sitaramc/gitolite">Gitolite</ulink></para>
 				<para><ulink url="http://subversion.tigris.org/">Subversion Home Page</ulink></para>
 				<para><ulink url="http://svnbook.red-bean.com/">Subversion Book</ulink></para>
                 <para><ulink url="https://help.ubuntu.com/community/EasyBazaar">Easy Bazaar Ubuntu Wiki page</ulink></para>