git.tex

\documentclass[11pt]{article}
\usepackage{fullpage}
\usepackage{url}
\usepackage{graphicx}
\usepackage{float}
\usepackage{dirtree}
\usepackage{fancyvrb}
\usepackage{indent first}

\newcounter{labquestion}
\newenvironment{question}{\stepcounter{labquestion} \begin{quote} {\bf
      Question \arabic{labquestion}.} }{\end{quote}}

\newcommand{\code}[1]{{\footnotesize\VerbatimInput{#1}}}

\begin{document}

\centerline{\Large\bf CSCI 121: Computer Science II}

\vspace{.1in}

\centerline{\large\bf Terminal and Git}

\vspace{.25in}

\noindent {\em Prerequisites:}

\begin{enumerate}
\item You have {\tt git} installed on your computer (you need the xCode command line tools on Mac).
\item You have the Java JDK and {\tt DrJava} installed on your computer.
\item You have a folder named {\tt cs121} in your home folder.
\end{enumerate}


\section*{Version Control}

In large-scale software projects, the team of developers use {\em version control} software to coordinate their collaborative work on the files in the project.  In this course we will introduce you to github, a popular version control system.  You will obtain copies of the base files for labs and projects, and you will also submit your solutions.  In this lab we will introduce you to the processes needed to interact with github.

Figure~\ref{workflow} shows the {\em workflow} of an assignment for this course.  Files will move between various {\em repositories} and your {\em sandbox}.  A repository is a location that holds all the versions of a file along with the timestamp and username of the person who edited the file.  Your sandbox is where you do your actual work, i.e.~editing and compiling files.  One of the benefits of this system is that it provides a backup system -- if you accidentally delete a file or make a change you want to undo, you can go back to previous versions from a repository.

\begin{figure}[H]
\centerline{\includegraphics[scale=.7]{workflow}}
\caption{The workflow for assignments in CSCI 121.}
\label{workflow}
\end{figure}

\section*{The Steps of Our Workflow}

\begin{enumerate}
\item {\bf Fork the assignment repository}:  {\em Fork} means that we are creating an exact duplicate of the repository.  As Figure~\ref{workflow} indicates, we will use github to hold the base repository and your forked version.  These repositories will be stored ``in the cloud'' on github's servers.

\item {\bf Clone your github repository}:  {\em Clone} is another way to create an exact duplicate of a repository.  In our workflow, we will clone the repository in your personal github account to the computer where you are working.  This can be an iMac in the computer lab or your personal laptop.

\item {\bf Checkout a copy of the files}:  The repository on your computer tracks all the changes to the files.  To do work, you must {\em checkout} a copy of the files.  These files are in your personal {\em sandbox}, and you can now make whatever changes are necessary to complete the assignment.

\item {\bf Commit your changes}:  Since the goal of a repository is to track the changes, we {\em commit} our work to the local repository at regular intervals.  You should commit work multiple times during an assignment to document your progress and to create backups.

\item {\bf Push your changes to github}:  When you complete the assignment, you {\em push} it from your local repository to the one on github.  All the commits you performed will be copied to github.

\item {\bf Make a pull request}:  To submit your work, you perform a {\em pull request}.  This will send a message to your instructor asking him to pull a copy of your github repository for grading.  Notice that your instructor will have a copy of the entire repository, not just the final version of your files.  This means that he will be able to see how your files changed over time!
\end{enumerate}

In the remainder of this lab we will walk you through a simple example of using this workflow.

\section*{Github}

Before you begin, you must create a github account.  You will use this account throughout your entire academic career, and it will document all the projects you work on.  Because this is a public record, many employers ask for your github username so they can see examples of your work.  Remember this as you select a username.

Go to \url{github.com} and create an account.  When prompted, select the (default) free personal plan.

\section*{Fork, Clone, and Checkout}

The assignments for this course will be posted at \url{github.com/csci121s15}.  The following steps will allow you to fork today's lab to your new github account, clone that repository to your computer, and then checkout a copy so we can do some actual work.

\begin{enumerate}
\item On the csci121s15 github page, click on the Git-Lab.  Then, at the top of the project page click on the \includegraphics[scale=.5]{fork} button.  This will create an exact copy of the repository in your github account.

\item When you fork the repository, github will take you to your copy, which you can see both from the URL and from the repository name at the top of the webpage.  In the lower-right, click in the text box labeled ``HTTPS clone URL'' and copy the text (CMD-C).

\item In a terminal go to your {\tt cs121} directory.  Next, type {\tt git clone} and then hit CMD-V to paste the HTTPS clone URL you copied earlier.  This command will clone your github repository to your computer.

\item {\tt git} assumes you want a copy of the current version of the files, so it automatically performed a checkout.  If you want, you can type command {\tt git checkout}, and it will tell you that you have the up-to-date version of the files.
\end{enumerate}

You are now ready for the rest of the lab.

\section*{Moving around in the Terminal}

To be effective using the terminal, it is important that you start to develop a mental picture of how files are organized on disk.  The following exercise gives you an opportunity to practice with the terminal.

In the terminal, we always have a {\em current directory}, which is the directory (also called a folder) where we are currently working.  You can always see your current directory by typing the command {\tt pwd}, which stands for ``print working directory.''  To move to a different directory, we use the command {\tt cd}, which stands for ``change directory.''  To list the contents of the current directory, we use the command {\tt ls}.  Please do the following:

\begin{enumerate}
\item You should be in the {\tt cs121} directory currently.  If not, type {\tt cd}, which takes you to your home directory, and then {\tt cd cs121}.

\item Use {\tt cd} to go to the {\tt Git-Lab} directory, and then use it again to go to the {\tt Sample} directory.\footnote{The terminal has an auto-complete feature where you can type the start of a name, hit the tab key, and it will complete the name for you.  You can also change multiple directories at a time.  A shortcut for what we just did is to type {\tt cd} and the letter 'G' and hit tab to complete the name {\tt Git-Lab}. The terminal adds a '/' to the end of the name because it is a folder, so you can now type 'S' and hit tab again to add sample.  You now have {\tt cd Git-Lab/Sample/}, and when you hit return, you go to the proper directory.}

\item Type {\tt ls} to see the files in the folder.  You should see four files lists.  One of the files is a folder.  To see that, type {\tt ls -F}.  The {\tt -F} is a {\em command line switch} that tells the {\tt ls} command to put a '/' after any file that is a directory.

\item Use {\tt cd} to go to the Data folder and {\tt ls} to see the three files in the folder.

\item Type {\tt cd ..} to go ``up'' one directory -- that is, back to the {\em Sample} directory.

\end{enumerate}

\newpage

We can visualize the directory structure of this folder as:

\dirtree{%
.1 Sample.
.2 Data.
.3 gigantic.dat.
.3 medium.dat.
.3 tiny.dat.
.2 Histogram.java.
.2 Main.java.
.2 Simulation.java.
}

\begin{question}
The {\tt Git-Lab} directory also contains a directory named {\tt Exercise}.  Using only the commands {\tt cd} and {\tt ls} in the terminal, explore the structure of the {\tt Exercise} directory and draw a picture similar to the one above.  Using a text editor such as TextEdit or TextWrangler, save the ``image'' as the file {\tt cs121/Git-Lab/Program/tree.txt}.\footnote{If you use TextEdit, be sure to change the format to ``Plain Text'' before saving.}
\end{question}

Before you continue, feel free to explore the {\tt Git-Lab} directory.

\section*{DrJava}

For the first half of the semester, we will use a programming environment called DrJava.  Please open DrJava and type the following program (changing the name to your name):

\code{First.java}

Save the code as {\tt cs121/Git-Lab/Program/First.java}.  You can compile your code by pressing F5, and you can run your program by pressing F2. 

\section*{Commit, Push, and Pull Request}

When you have a working program, you are ready to submit your lab.  During this process you will specify which files to commit and then add a message saying what changes you made.

First we will configure {\tt git} to auto-complete some values for you and to use a friendly editor:

\begin{enumerate}
\item Type {\tt git config --global core.editor nano} to make {\tt git} use the {\tt nano} editor instead of {\tt vi}.
\item Type {\tt git config --global user.name "John Doe"} with your name in quotes to have commits tagged with your name.
\item Type {\tt git config --global user.email "johndoe@example.com"} with your email address to have commits tagged with your email address.
\item Change directory to {\tt Git-Lab/Program} and list the files.  You should see three files, {\tt First.java}, {\tt First.java\textasciitilde}, and {\tt First.class}.  The file ending in a tilde is a backup file, and the .class file is the compiled version.  {\em We only put source files in repositories.}
\item Type {\tt git add First.java} to tell {\tt git} that the changes to this file should go into the next commit.  You should also add {\tt tree.txt} in the same way.  If you type {\tt git status} it will show you the status of the files in your repository.
\item Type {\tt git commit} and an editor window will open.  This is where you write a log message that will be permanently associated with the changes to the file.  In this case, we can simply say that we created this file to practice with Java.  When you exit, save as the recommended name.
\item Your changes are now in the repository on your computer.  To get them to github, type {\tt git push}.  This will prompt you for your github username and password.
\item On the github webpage you can now see the changes that you made.  On the webpage, navigate into the Program folder and click on {\tt First.java} to see how github shows changes.
\item To send your code to your instructor you will submit a pull request.  On the main github page for this repository, click on the link ``Pull Requests'' on the right side of the page.  Click the green ``New pull request'' button, and make sure the proper changes are being sent.  Click ``Create pull request,'' fill in the title, and comment, and then click ``Create pull request'' to finalize your request.
\end{enumerate}

Congratulations!  You have successfully completed the first lab.

\section*{More information}

\begin{itemize}
\item If you want to learn more about using {\tt git} at the command line, try the online tutorial at:

\url{https://try.github.io/}.

\item As mentioned in the lab, we only want to put {\em source} files in the repository.  You can teach git to ignore files like {\tt First.class} and {\tt First.java\textasciitilde} by adding the following lines to the file {\tt .gitignore} in the {\tt Git-Lab} directory:

\begin{verbatim}
*.class
*~
\end{verbatim}

\end{itemize}

\end{document}