Some Notes on How to Use GitHub for a First-Time User

With multiple editors of the same document it is useful to have some sane way of preventing multiple versions floating around. GitHub provides a central server, offsite, and a communication system to support collaboration.

With the LSST white paper, the concept is that you copy the LSST repository to your local machine and edit it there. Your personal fork on GitHub is where you put your final edits for LSST to pull them in. You can edit directly on your personal github fork, but their editor is primitive and you cannot do any of the latex commands.

So....

On Github:
                                   fork
           [your-fork] <------------------------------- [main LSST repository] (latex files, figures)
                       -------------------------------->
             /\   ||      submit pull request to LSST
             ||   ||        to pull in your changes
          p  ||   || c
          u  ||   || l
          s  ||   || o
          h  ||   || n
             ||   || e
             ||   \/
       Your local machine 

A `clone' copies of all the files from the fork to your local machine. Edit them locally, run 'make' to do the latex
and to generate a .pdf for preview. Then `push' the changes onto your GitHub fork, and ask LSST to add them to 
the main document via a `pull request'. A `pull' is the opposite of a `push'.



Procedure

Log on to github
Create a fork of github.com:LSSTScienceCollaborations/ObservingStrategy.git by navigating to this directory and clicking the fork symbol in the upper right of the page. This copies the latest version to your personal github directory

If you already have a fork that needs updating, either

(a) remake it - go to your personal fork repository on github
                Settings tab (wheel symbol at top right)
                Scroll to bottom, click 'Delete this repository'
                Now initialize a new fork via https://github.com/LSSTScienceCollaborations/ObservingStrategy
                And click the fork symbol in the upper right. It will create the fork and
                 move you back to your directory (note the url change on the browser)
....or
(b) update it - go to https://github.com/LSSTScienceCollaborations/ObservingStrategy
                click 'New Pull Request' button
                 pull requests work both ways, so you need to be clear about what gets pulled where
                click 'compare across forks' link
                base fork: your fork
                head fork: LSSTScienceCollaborations/ObservingStrategy
                 choose master branch for both
                 it should say how many changes have been made relative to your fork
                enter a message 'pull in updates'
                click 'Create Pull Request'
                click 'merge pull request' and 'confirm merge'
On the local machine you need to generate an ssh-key and put it on github before you can clone.
See https://help.github.com/articles/generating-an-ssh-key/
You basically run ssh-keygen, create a passphrase, and grab the characters in the id_pub file in the .ssh directory and paste them into the GitHub sshkey box.

If your local machine does not have the git unix command you will need to find that package and add it to your computer (e.g. via yum)

on the local machine, make a github directory. Then
git clone git@github.com:yourname/ObservingStrategy.git
Creates a clone of your forked repository on the local machine.

At any time, to keep up your clone up to date with the base LSST repository, connect via
git remote add base git@github.com:LSSTScienceCollaborations/ObservingStrategy.git
git pull base master

Edit the files you want to change.
To typeset locally, use "make" in the whitepaper directory. Hopefully you have all the style files they are using.
git commit -am "comment"
git status
git push origin master
This pushes the edits to your personal github fork, which is the origin of the clone

Submit a pull request on the GitHub site. Owners of the LSST site will then pull in your edits if they like them.


Back to Hartigan's Home Page
Patrick Hartigan
hartigan@sparky.rice.edu