Git and Fab

Git and Fab
This is a quick tutorial intended to show users who are familiar with version
control systems how to use git with SiteServer.  It does not cover installation
of git, use of the command line, the mechanics of version control, and other
advanced topics.  Git requires some somewhat advanced skills to get started,
but if you are up to the challenge, it is probably easier and nicer to use than
the web interface to siteserver.  If this daunts you, just use the web interface
- it does everything you'll need to do.

Contents:
   * Git vs. traditional version control
   * Using git with Fab servers
   * Further reading

Git vs. SVN/CVS/etc
Unlike SVN or CVS which operate on a model where a central server stores the
whole repository and associated version control information, git is distributed
- every checked out copy of a git repository is both the version control server
and the checked out data.  A diagram makes this clearer:

    Traditional Version Control System (CVS, SVN):
    
    The server contains the only copy of the version control system.  Each 
    client copy contains only the latest changes.  

    Git works differently:
    
    Every client has a complete version control system with all changes locally.
    Clients working copies are of the latest changes.  When you wish to synchronize
    with other clients or a server, you must "push" or "pull", merging your 
    repository's changes with the server's.

Here are some important commands, and their rough equivalents in a system
like SVN:

Git command	Function	Rough equivalent in SVN	Difference
git clone http://example.com/repository	Creates a local copy of the repository, and checks out working files for the latest changes	svn co http://example.com/repository	svn only checks out a working set, not a full copy of the repository
git add .	Recursively add all changes from the current directory on down to the local repository.	svn add .	svn does not handle file additions and deletions as cleanly as git.
git commit	Commits all changes to the local repository.	svn ci	svn checks in to the remote repository, as there is no local repository.
git push	Merges local changes with the remote repository from which the local repository was originally cloned.	(no equivalent)
git pull	Merges remote repository with local repository.	(no equivalent)


Using git with fab servers
All of the SiteServer websites are backed by git repositories.  Because git is
a distributed version control system with no authoritative central server, this
becomes slightly complicated.  It may be helpful to consider the following
diagram in order to understand the process:

Because the webserver with the siteserver interface is itself just another git
repository that is a clone of the git server (just like your local copy is), it
is necessary to commit changes made via the siteserver interface and push/pull
those changes to the bare repository from which you make your clone, in the
same way that your local copy does.  In other words, both the website and you
are just copies of a third intermediary, the main git server.

Setting up a git clone on your computer
   1.  Set up ssh for use with fab servers.
      For security purposes, we don't detail passwords, urls, or ssh settings
      here.  Contact someone who knows to gain access.
   2.  Clone the git repository.  The command will be somthing like:

         git clone http://example.com/path/to/repository

Synching siteserver to git repository
   1.  Pull any changes from the git server to the website.  Find
      the following control line in the siteserver interface:
      
      Press the "pull" button.
   2.  Commit the website's changes to the repository. Enter a commit
      message into the text box, and press enter.  
   3.  Push the website's changes to the main git server by pressing
      the "push" button.

Synching local changes with website
    After making changes on your own computer to a working set that you
    cloned from the main git server, you'll want to commit it back to the
    website.
    1.  Pull any changes from the git server to your local copy:
         
         git pull

    2.  Add any new files to version control.  From a directory above
       any changes you've made, type:

         git add .

    3.  Commit changes to the local repository.  (The "-a" switch 
       tells git to automatically handle new and removed files):

         git commit -a -m "type commit message here"

    4.  Push changes to the repository.

         git push

    5.  Update the website with the repository's new changes.  Go
       back to siteserver, and press the "pull" button.
         
Further Reading
Git is a very advanced tool with many many options, and I have only just
grazed the surface here.  Some useful resources:
   * Git developer's website
   * Git tutorial
   * Google for "git howto" or "git tutorial"