Daily Archives: March 7, 2010

How to Install and Get Up and Running Quickly with GIT – a Fast, Distributed Version Control System.

Git LogoI have recently installed and used Git for the first time and I have been impressed by its excellent modular and distributed design, speed, efficiency and usefulness.  So what is Git?

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.  It may be used as a source control management system by software developers.  However, it has a much wider remit and may be used as a version control system for all documents, spreadsheets, presentations and so on.

For some people approaching Git for the first time, it may appear somewhat daunting and overwhelming – not sure where to start, and then how to proceed once on the journey. Thus, the purpose of this article is to provide concise tips and references to facilitate you to get up and running quickly with Git.

Benefits of Version Control

Before jumping into the technical details, I want to briefly outline some of the benefits of a Version Control System (VCS).  They include:

  • Providing snapshots of your documents and the ability to easily go back to an earlier version/revision of your work.
  • Facilitating an efficient and well managed organisation of documents. Experienced document authors compensate for not having a document management system by developing their own naming conventions for each document revision.  As a result, their Documents folder is littered with many revisions of documents using specialized file naming conventions such as file name – date – revision.ext.  A version control system replaces this chaos with a well structured consistent, reliable, efficient and easily managed organisational structure that allows you to focus on the work at hand – the content of your documents.
  • Provides accountability – the ability to maintain and search what was edited when and by whom and what they did.  This is of particular importance when working in a team or collaborating with external members.
  • Adapting to use whatever workflow is appropriate for your project – centralised, distributed, Gatekeeper, and so on.
  • A real time-line of effort put in to complete a project – helps in estimating new projects and billing complete ones.
  • Provision of a backup service (if using a remotely hosted source control solution).
  • Parking projects and then taking them up months/years later and jumping right in by reviewing your comments on what you already did up to the point where you left off.
  • Take risks and make changes knowing that you can always restore a project to a point in time.
  • The ability to create new “branch”  versions. This feature can be useful for making bug fixes when projects have already been released to the field and the next build of the project is in development.
  • Branching also facilitates parallel development. If several people are working on the same project, an integration branch can be created. When any party has new working code, it can be merged to the integration branch where all parties can use the change.
  • Conserving disk space – The VCS only stores the latest version of a file and the differences between each version that precedes it.  Thus the disk space required is usually several orders of magnitudes smaller than what would be required with a VCS.

Install Git and Get up and Running Quickly

  1. If you are new to version control, it is highly recommended you familiarize yourself with the concepts.  An excellent visual introductory guide to version control is available online.
  2. To Install Git on Windows:
    1. There are several different Git installation packages available for installation on Windows.
      I recommend you download and install GitExtensions (which includes MSysGit and KDiff3).  It has the following features:

      • Windows Explorer integration for Git.
      • Visual Studio (2005,2008,2010) plugin for Git.
      • Can be integrated with the Eclipse IDE.
      • Feature rich user interface for Git.
      • Single installer installs Git (MSysGit), GitExtensions, Putty and the merge tool KDiff3.
      • 32bit and 64bit support.
    2. A step-by-step screenshot analysis of each stage of the installation process is available.  In essence, accept the default settings at each stage.
    3. Note: I suggest one change to the default settings:
      When prompted to Adjust your path environment during the Git installation, I recommend selecting:
      Run Git from the Windows Command Prompt
      This will simply allow you to run Git from the command prompt regardless of your current working folder.
  3. To install Git on Ubuntu Linux:
    1. The version installed by apt-get is quite old.  There are simple instructions available to install the latest current stable version here. I recommend installing git-core, git-doc, gitk and git-gui.
  4. To Create a New Repository using the graphical user interface:
    1. Run Git Gui.
    2. Create a new Repository and choose a project folder.
    3. Select everything under Unstaged Changes.
    4. From the MenuBar, Select Commit | Stage to Commit
    5. In the box on the bottom-right of Git Gui, labeled Initial Commit Message, Enter the commit message.
      • The message may include such details as:
        Title_of_Commit
        Name_of_commiter: Joe Bloggs
        Date: 01-01-2000
        Version: 00.01.00
        Description of Changed made:  Several line description.
    6. Select the commit button beside bottom window.
  5. To Create a New Repository using the command line:
    It is even easier to create a new repository from the command line.

    1. Open up a command prompt (windows) or terminal (Linux) and change directory to the project folder. Then enter the following commands:
      1. To create the new repository:
        git init
      2. To add all the contents of the folder into the Git repository:
        git add .
      3. Finally, to commit the files to the repository:
        git commit -m “InitialisedRepository”
  6. To Configure the Eclipse IDE to use Git Gui as an embedded version control management tool:
    There are two excellent and short video tutorials on Youtube to demonstrate this.

    1. Using Git GUI with Eclipse Part I – Setting up the workspace
    2. Using Git GUI with Eclipse Part II – Pushing changes to the server

    Indeed, the method outlined in the videos may be used to integrate Git Gui with any software application that supports external tool configuration and invocation.

Online Resources to help you on your way

  1. Some excellent online resources for learning and using Git:
    • ProGit – An excellent resource for someone new to Git.
  2. Some excellent video screencasts explaining how to use Git:

Git Tips

  1. To configure Git to use an Internet Proxy:
    If your computer passes through a Proxy in order to access the Internet, then Git must be configured to use this Proxy when interacting with repositories on the Internet.  The command to enable Git to use a Proxy is:
    git config –global http.proxy http://our-proxy-server:8088
  2. To configure Git to ignore certain file types:
    Git may be configured to ignore certain filetypes by placing entries in the GIT_DIR/info/exclude file located in the project folder.
    Note: This file must be ready before any files are committed to the Git repository (i.e.: immediately after git init).

    1. The entries may be as follows:
      *.aux
      *.log
      *.blg
      *.[oa]
      filename.ext
    2. For more information, refer to the relevant chapter in the online Git Community Book.
  3. To checkout just one or two files from an older version to be included in the current version:
    Occasionally it may be necessary to check out an old version of just one file and include it in the current working branch (as opposed to checking out the entire older branch just to get that one particular file)  The instructions are in the Git User manual.
  4. To setup your own Git Host Repository:
    There is an excellent guide online explaining step-by-step how to setup a (simple) new remote online repository.
    The steps detailing how to setup a more advanced GIT host repository with automatic user management on a Ubuntu server with clients connecting from Windows are available here.

To access (push, pull and fetch) a GitHub repository from behind a proxy.

The original reference for these instruction are available here.

The typical scenario behind a proxy is:

  • All internet access passes through a proxy.
  • The proxy allows outward connections of type HTTP and HTTPS only (ports 80 and 443 respectively).
  • The CONNECT method is only enabled for port 443.
  • Optionally, proxy authentication is required.

Windows Platform

  1. Install GitExtensions (as described earlier).
  2. Generate your SSH key if you have not already done so and add it to your GitHub account (instructions are available online).  It is also highly recommended you generate a passphrase from reasons outlined here.
    Note: Using Git Gui you may generate your SSH key and  passphrase very easily from the menu bar by selecting Help | Show SSH Key | Generate Key.
  3. Download the utility connect which permits the tunneling of various network connectinos via HTTP(S) proxies.
    The source code connect.c is available for download and compilation.  A pre-compiled binary for windows users is available.
    I placed connect.exe in  C:\software\connect\connect.exe
  4. Backup your existing SSH config file (if it exists).
  5. Create a new SSH config file called config-proxy and place the following text in that file.
    (Note: the text from ProxyCommand to %p should be on one line with a space after “-H”).ProxyCommand C:/software/connect/connect.exe -H proxy.site.com:443 %h %p
    Host github.com
    User git
    Port 22
    Hostname github.com
    IdentityFile “C:\Users\username\.ssh\id.rsa”
    TCPKeepAlive yes
    IdentitiesOnly yes

    Host ssh.github.com
    User git
    Port 443
    Hostname ssh.github.com
    IdentityFile “C:\Users\username\.ssh\id.rsa”
    TCPKeepAlive yes
    IdentitiesOnly yes

  6. Finally, when connecting to your Github repository, specify the remote location as follows (replacing the uppercase words to the appropriate values corresponding to your details):
    ssh://git@ssh.github.com:443/USERNAME/PROJECTNAME.git
    For example, to clone an existing project:
    git clone ssh://git@ssh.github.com:443/USERNAME/PROJECTNAME.git
  7. That’s it!

Google Tech Talks

  • What is Git – A talk by Randal Schwartz.  He presents a good technical overview of Git.
  • Linus Torvalds, the creator of Git, visited Google to share his thoughts on the source control management system. This high-level talk highlights the differences between Git and the alternative version control systems and is quite entertaining as Linus as some strong views on technical matters and design philosophies

How to Install a Full MiKTeX LaTeX Installation and configure TeXnicCenter on Windows XP, Windows Vista and Windows 7

TeXnicCenter LogoThe purpose of this article is to outline in concise form the steps required to install and configure a full LaTeX distribution from scratch up to the point of editing documents in LaTeX on a Windows PC.  Furthermore, I will show you how to integrate the LaTeX editor with the PDF viewer to enable you to switch seamlessly between them while creating your documents.

The LaTeX editor employed here is the free open source TeXnicCenter editor which provides all the functionality you need to create, write, build, view and print your LaTeX documents.

Adobe Reader iconPlease ensure you have a PDF viewer already installed before commencing the steps below.  This article will provide instructions on how to configure and integrate two PDF viewers with our LaTeX editor: the free open source PDF viewer Sumatra PDF and the freeware Adobe Acrobat Reader.  You may install either one (or both if you wish).

This article provides instructions for the following platforms: Windows XP, Windows Vista and Windows 7.

  1. Download and run the free open source MiKTeX Net Installer setup-2.X.xxxx.exe from the MiKteX download page. The MiKTeX installation consists of two phases:  the first phase will download the MiKTeX distribution to your PC, the second phase will perform the actual installation.  Once the download operation has finished, the first phase is complete and you are ready to install MiKTeX.  It is recommended to download the latest stable version.  At the time of writing, the latest stable version is 2.9.
  2. To perform the second phase of the installation, start Windows Explorer and browse to the directory which contains the complete MiKTeX distribution (where you downloaded it). Look for a file named setup.exe.   This is the MiKTeX Setup application.  Run setup.exe by double-clicking its icon.  When asked to select a repository folder, select the location of the downloaded MiKTeX distribution. Please be patient as the installation may take quite some time to complete.
  3. Update the MiKTeX Installation:
    From the Start menu, 

    1. On Windows XP:
      select  Start | Programs | MiKTeX 2.X | Update
    2. On Windows Vista or Windows 7:
      select  Start | Programs | MiKTeX 2.X | Maintenance (Admin) | Update (Admin)
    3. Select the option:
      I want to get updated packages from a remote package repository
      and the option:
      Let me choose a remote package repository
      and select the repository nearest you.
    4. Follow the onscreen instructions.
  4. Update the MiKTeX Package Manager:
    From the Start menu, 

    1. On Windows XP:
      select Start | Programs | MiKTeX 2.X | Settings
    2. On Windows Vista or Windows 7:
      select  Start | Programs | MiKTeX 2.X | Maintenance (Admin) | Settings (Admin)
    3. Select the option Refresh FNDB
    4. Select the option Update Formats
    5. Exit the application by clicking Ok.
  5. Install TeXnicCenter:
    1. Download the latest version of TeXnicCenter from http://www.texniccenter.org
    2. Run the TeXnicCenter installer and follow the onscreen instructions.
  6. Configure TeXnicCenter’s initial settings:
    1. When running TeXnicCenter for the first time, follow the onscreen instructions.
    2. Close and rerun TeXnicCenter.
    3. Select Tools | Options | Editor Tab
      Enable display line numbers
  7. If you are running Windows Vista or Windows 7:
    1. Configure the TeXnicCenter application to run as an administrator.
    2. Configure the TeXnicCenter application to run in compatibility mode: Windows XP SP3.
    3. If you will use Sumatra PDF as your PDF viewer, configure the Sumatra PDF application to run in compatibility mode: Windows XP SP3.
  8. A brief explanation of terminology concerning Integration features between TeXnicCenter and the PDF viewers is now required.
    Several PDF viewers support the concept of Forward-Search and Inverse-Search. 

    • What is Forward-Search?: When compiling (generating PDF output) your LaTeX source document in TeXnicCenter, Forward-Search enables the current editing location in the source latex file to be displayed and highlighted in the generated PDF.  For example, if you are editing text that appears on page 8 of the PDF; after compiling the LaTeX source, the PDF viewer will open the document and jump directly to page 8 to display the text you have just edited.  This is a great timesaver.  The communication between the editor and PDF viewer often relies on the DDE protocol.
    • What is Inverse-Search?: Inverse-Search is a synchronisation feature whereby doubling-clicking on a line in the PDF document will switch to the LaTeX editor and display the corresponding line in the document source.  Again, another great timesaver.
    • Adobe Reader and Adobe Acrobat:
      Forward-Search and Inverse-Search may not work with adobe Reader version 8 or higher (i.e.: all recent versions).
    • Sumatra PDF Viewer:
      Forward-Search and Inverse-Search function correctly using Sumatra PDF on Windows XP SP3, Windows Vista and Windows 7. This author’s preference is to use the Sumatra PDF viewer to view the document during the creation and editing phases, and only use Adobe Reader to view the final completed document to verify the final document version appears correctly when viewed with Adobe Reader.
      Note 1: At present (TeXnicCenter v1.0 and Sumatra V1.3), forward search only works if the file name and entire file path do not contain spaces!
      Note 2: Be aware that cutting and pasting the configuration information that appears in the subsequent steps from this webpage directly into the TeXnicCenter configuration panel may not work.  The double-quotes (and single-quotes) are often misrepresented.
  9. To configure TeXnicCenter to view document output using Adobe Reader:
    1. Run TeXnicCenter.
    2. Select Build | Define Output Profiles | Viewer Tab
    3. Ensure the profile selected is LaTeX => PDF
      For both View Project’s Output and Forward Search options, enter the following: 

      1. Enable DDE
      2. Command: [DocOpen(“%bm.pdf”)][FileOpen(“%bm.pdf”)]
      3. Server: acroview
      4. Topic: control
    4. For Close Document before running LaTeX:
      1. Enable DDE
      2. Command: [DocClose(“%bm.pdf”)]
      3. Server: acroview
      4. Topic: control
  10. To configure TeXnicCenter to view document output using Sumatra PDF:
    The Sumatra PDF viewer integrates nicely with TeXnicCenter supporting both forward-search and inverse-search. 

    1. Run TeXnicCenter.
    2. Select Build | Define Output Profiles | (La)Tex Tab
      1. Select Add to add a new profile.
        Enter the profile name:  Latex => PDF (Sumatra)
    3. Under the (La)TeX Tab
      1. Select the checkbox:  Run (La)TeX compiler
        1. Path to the latex compiler:
          C:\software\MiKTeX 2.8\miktex\bin\pdflatex.exe
          Note: The path references may be different on your computer.
        2. Command line arguments to pass to the compiler:
          -interaction=nonstopmode “%pm” -synctex=-1
      2. Unselect the checkbox:  Do not use BibTeX in this profile
         

        1. Path to BibTeX executable:
          C:\software\MiKTeX 2.8\miktex\bin\bibtex.exe
        2. Command lne arguments to pass to BibTeX:
          “%bm”
      3. Unselect the checkbox:  MakeIndex
        1. Path to MakeIndex executable:
          C:\software\MiKTeX 2.8\miktex
          \bin\makeindex.exe
          Note: The path should be on one line, I split the path here to ensure it displays clearly. There should be no space  at the line break between miktex and \bin.
        2. Command line arguments to pass to MakeIndex:
          “%bm”
    4. The Postprocessor tab may be left blank.
    5. Under the Viewer Tab:
      1. Path to executable:
        C:\software\SumatraPDF\SumatraPDF.exe
        -inverse-search “\”C:\software\TeXnicCenter\TEXCNTR.EXE\”
        /ddecmd \”[goto(‘%f’,’%l’)]\””
        Note: The path should be on one line, I split the path here to ensure it displays clearly.  There should be a space inserted at the position of the line breaks:
         

        • one space after SumatraPDF.EXE
        • another space after TEXCNTR.EXE\“
      2. For View project’s output:
        1. Enable Command line argument
        2. Command: “%bm.pdf”
      3. For Forward Search:
         

        1. Enable DDE command:
        2. Command: [ForwardSearch(“%bm.pdf”,”%Wc”,%l,0)]
        3. Server: sumatra
        4. Topic: control
      4. For Close document before running (La)Tex
        1. Enable Do not close.
  11. Well Done!  You are now ready to create beautifully typesetted PDF documents.  Enjoy!

References