share-your-code.tex

\section*{Share your code}

Once you have your files saved in a Git repository, you can share it with your collaborators and the wider scientific community by putting your code online (Fig. \ref{fig:Fig3}).
This also has the added benefit of creating a backup of your scripts and provides a mechanism for transferring your files across multiple computers.
Sharing a repository is made easier if you use one of the many online services that host Git repositories (Table 1), e.g. GitHub.
Note, however, that any files that have not been tracked with at least one commit are not included in the Git repository, even if they are located within the same directory on your local computer (see Box 2 for advice on the types of files that should not be versioned with Git and Box 3 for advice on managing large files).

Below we focus on the technical aspects of sharing your code.
However, there are also other issues to consider when deciding if and how you are going to make your code available to others.
For quick advice on these subjects, see Box 4 on how to license your code, Box 5 on concerns about being scooped, and Box 6 on the increasing trend of journals to institute sharing policies that require authors to deposit code in a public archive upon publication.

To begin using GitHub, you will first need to sign up for an account.
For the code examples in this tutorial, you will need to replace \verb|username| with the username of your account.
Next choose the option to ``Create a new repository'' (Fig. \ref{fig:Fig3}B, see \href{https://help.github.com/articles/create-a-repo/}{help.github.com/articles/create-a-repo}).
Call it ``thesis'' because that is the directory name containing the files on your computer, but note that you can give it a different name on GitHub if you wish.
Also, now that the code will be existing in multiple places, you need to learn some more terminology (Box 1).
A local repository refers to code that is stored on the machine you are using, e.g. your laptop; whereas, a remote repository refers to the code that is hosted online.
Thus, you have just created a remote repository.

Now you need to send the code on your computer to GitHub.
The key to this is the URL that GitHub assigns your newly created remote repository.
It will have the form \verb|https://github.com/username/thesis.git| (see \href{https://help.github.com/articles/cloning-a-repository/}{help.github.com/articles/cloning-a-repository}).
Notice that this URL is using the HTTPS protocol, which is the quickest to begin using.
However it requires you to enter your username and password when communicating with GitHub, so you'll want to considering switching to the SSH protocol once you are regularly using Git and GitHub (see \href{https://help.github.com/articles/generating-ssh-keys/}{help.github.com/articles/generating-ssh-keys} for directions).
In order to link the local thesis repository on your computer to the remote repository you just created, in your local repository you need to tell Git the URL of the remote repository using the command \verb|git remote add| (Fig. \ref{fig:Fig3}C).

\begin{verbatim}
$ git remote add origin https://github.com/username/thesis.git
\end{verbatim}

The name ``origin'' is a bookmark for the remote repository so that you do not have to type out the full URL every time you transfer your changes (this is the default name for a remote repository, but you could use another name if you like).

Send your code to GitHub using the command \verb|git push| (Fig. \ref{fig:Fig3}D).

\begin{verbatim}
$ git push origin master
\end{verbatim}

You first specify the remote repository, ``origin''.
Second, you tell Git to push to the ``master'' copy of the repository - we will not go into other options in this tutorial, but Box 7 discusses them briefly.

Pushing to GitHub also has the added benefit of backing up your code in case anything were to happen to your computer.
Also, it can be used to manually transfer your code across multiple machines, similar to a service like Dropbox (\href{www.dropbox.com}{dropbox.com}), but with the added capabilities and control of Git.
For example, what if you wanted to work on your code on your computer at home?
You can download the Git repository using the command \verb|git clone|.

\begin{verbatim}
$ git clone https://github.com/username/thesis.git
\end{verbatim}

By default, this will download the Git repository into a local directory named ``thesis''.
Furthermore, the remote ``origin'' will automatically be added so that you can easily push your changes back to GitHub.
You now have copies of your repository on your work computer, your GitHub account online, and your home computer.
You can make changes, commit them on your home computer, and send those commits to the remote repository with \verb|git push|, just as you did on your work computer.

Then the next day back at your work computer, you could update the code with the changes you made the previous evening using the command \verb|git pull|.

\begin{verbatim}
$ git pull origin master
\end{verbatim}

This pulls in all the commits that you had previously pushed to the GitHub remote repository from your home computer.
In this workflow, you are essentially collaborating with yourself as you work from multiple computers.
If you are working on a project with just one or two other collaborators, you could extend this workflow so that they could edit the code in the same way.
You can do this by adding them as Collaborators on your repository (Settings -\textgreater Collaborators -\textgreater Add collaborator, see \href{https://help.github.com/articles/adding-collaborators-to-a-personal-repository/}{help.github.com/articles/adding-collaborators-to-a-personal-repository}).
However, with projects with lots of contributors, GitHub provides a workflow for finer-grained control of the code development.

With the addition of a GitHub account and a few commands for sending and receiving code, you can now share your code with others, transfer your code across multiple machines, and setup simple collaborative workflows.