git.tex

\section{Git}
\label{Git}

The ROMS source code is distributed using subversion (\ref{Svn}),
but one way to download it is via \href{https://git-scm.com/}{git}
and git-svn. The best book I've read on it is free online at
\href{https://git-scm.com/book/en/v2}{Pro Git} \citep{Pro_Git}.
I have also rambled at length about \code{git}
on the \href{https://www.myroms.org/wiki/index.php/ROMS_git}{ROMS
wiki}.

\subsection{Overview}
Git is a tool for managing software development that keeps
track of who modified what and allows the return to a previous
version if changes don't work as expected. It was designed to:
\begin{itemize}
  \item be able to manage a huge team of developers
  \item be fast
  \item be distributed
  \item be open source
\end{itemize}

\subsection{Setup}
Prior to running git, it is best to tell it who you are on each
system:
\begin{verbatim}
    git config --global user.name “me”
    git config --global user.email “me@work”
    git config --global color.ui “auto”
    git config --list
\end{verbatim}
The first two commands provide your name and email address while the
third tells \code{git} to use color. The last command is simply a
query to as what config options you have set.

\subsection{Checking out the code}
WARNING: It is strongly suggested that you checkout the ROMS source
code using the same operating system you wish to compile and run
ROMS on. If you download the code on a Windows machine and wish to
run it on a non-Windows machine you will need convert the line
endings with a utility like dos2unix or recode. Even with these
utilities you may still have problems compiling ROMS.

To check-out the files from the ROMS repository trunk:
\begin{verbatim}
    git svn clone [-r xxx] https://www.myroms.org/svn/src/trunk MyDir
\end{verbatim}
where MyDir is the destination directory on your local computer.

\subsection{Updates}
Now and again, you might feel the urge to get up to speed with the
latest changes that have been made to the ROMS repository. When that
happens, simply go to the directory that was ``MyDir'' above and
type:
\begin{verbatim}
    svn update
\end{verbatim}
Subversion will remember where you checked out from before and
see if a newer revision exists. If so, it will download and apply
all the relevant changes.

\subsection{Code changes}
As you use ROMS, you may find yourself adding new files and new chunks of
code to existing files. Unless you are a developer with write access to the
repository at www.myroms.org, you have no easy way to save your changes
within the svn framework, since any one directory can only point to one
repository. To keep getting updates from the trunk, you must keep using the
svn server at myroms.org. At the very least, saving a tarball before
fetching major updates is a prudent step.

\subsection{Conflicts}
Sometimes when you make changes to your copy of the ROMS code, those changes
will conflict with changes made to the repository. This means that the
changes from the server overlapped with your own, and now you have to
manually choose between them.

Whenever a conflict occurs, three things typically occur to assist you in
resolving that conflict:
\begin{itemize}
        \item Subversion halts during the update, offering you several choices,
and remembers that the file is in a state of conflict if you don't clear it
right then.
        \item If Subversion considers the file to be mergeable, it places
conflict markers (special strings of text which delimit the ``sides'' of the
conflict, usually ``<'' and ``>'' characters) into the file to visibly
demonstrate the overlapping areas.
        \item For every conflicted file, Subversion places three extra
unversioned (not under Subversion control) files in your working copy: 
\begin{klist}
            \kitem{filename.mine}: This is your file as it existed
      in your working copy (local copy) before you updated your working
      copy. This file has only your latest changes in it. (If Subversion
      considers the file to be unmergeable, then the .mine file isn't
      created, since it would be identical to the working file.)
            \kitem{filename.rOLDREV}: This is the file that was the
      BASE revision before you updated your working copy. That is,
      the file that you checked out before you made your latest edits.
            \kitem{filename.rNEWREV}: This is the file that your
      Subversion client just received from the server when you updated
      your working copy. This file corresponds to the HEAD (latest)
      revision of the repository.
  \end{klist}
\end{itemize}
For example, let's say you checked out revision 280 and made some changes
to a file, for instance \code{User/Functionals/ana\_hmixcoef.h}.
Now you want to update your
ROMS source code to take advantage of a new algorithm but when you run
svn update your \code{ana\_hmixcoef.h} is now in conflict with the new
version in the repository:
\begin{verbatim}
    > svn update
    U Version
    U ROMS/Modules/mod_mixing.F
    U ROMS/Functionals/ana_hmixcoef.h
    C User/Functionals/ana_hmixcoef.h
    Updated to revision 291.

    >
\end{verbatim}
The above is with an older version of svn. The latest, greatest does this:
\begin{verbatim}
    Conflict discovered in 'ROMS/Utility/inp_par.F'.
    Select: (p) postpone, (df) diff-full, (e) edit,
    (mc) mine-conflict, (tc) theirs-conflict,
    (s) show all options:
\end{verbatim}
Selecting (p) will behave as the old version.

If you get a conflict, you need to do one of three things:
\begin{itemize}
        \item Merge the conflicted text ``by hand'' by examining and
     editing the conflict markers within the file.
        \item Copy one of the temporary files on top of your working file.
        \item Run svn revert <filename> to throw away all of your local
     changes.
\end{itemize}
Once you've resolved the conflict, you need to let Subversion know by
running ``svn resolved''. This removes the three temporary files and
Subversion no longer considers the file to be in a state of conflict. More
on this below.

\subsubsection{Merging conflicts by hand}
To merge your changes with those from the latest revision in the repository,
open \code{ana\_hmixcoef.h} in your favorite editor and
look for a string of ``<'' characters. You should see something like this:
\begin{verbatim}
    <<<<<<< .mine
    #ifndef DISTRIBUTE
    IF (Lanafile.and.(tile.eq.0)) THEN
    #else
    IF (Lanafile) THEN
    #endif
    =======
    #ifdef DISTRIBUTE
    IF (Lanafile) THEN
    #else
    IF (Lanafile.and.(tile.eq.0)) THEN
    #endif
    >>>>>>> .r291
\end{verbatim}
After comparing the two code blocks (separated by the ``='' symbols), you
decide that you prefer the logic from the repository so you remove the
conflict markers and your code so the section now looks like this:
\begin{verbatim}
    #ifdef DISTRIBUTE
    IF (Lanafile) THEN
    #else
    IF (Lanafile.and.(tile.eq.0)) THEN
    #endif
\end{verbatim}

Now you can save the file and let Subversion know that you have resolved the
conflict:
\begin{verbatim}
    > svn resolved User/Functionals/ana_hmixcoef.h
    Resolved conflicted state of 'User/Functionals/ana_hmixcoef.h'
\end{verbatim}

\subsubsection{Copying a file onto your working file}
If you get a conflict and decide that you want to throw out your changes,
you can merely copy one of the temporary files created by Subversion over
the file in your working copy. Let's say you want to use the new revision
from the repository:
\begin{verbatim}
    > cd User/Functionals
    > ls ana_hmixcoef.h*
    ana_hmixcoef.h ana_hmixcoef.h.mine ana_hmixcoef.h.r280
    ana_hmixcoef.h.r291

    > cp ana_hmixcoef.h.r291 ana_hmixcoef.h
    > svn resolved ana_hmixcoef.h
    Resolved conflicted state of 'ana_hmixcoef.h'
\end{verbatim}

\subsubsection{Punting: Using svn revert}
If you get a conflict, and upon examination decide that you want to throw
out your changes and start your edits again, just revert your changes:
\begin{verbatim}
    > cd User/Functionals
    > svn revert ana_hmixcoef.h
    Reverted 'ana_hmixcoef.h'
\end{verbatim}
Note that when you revert a conflicted file, you don't have to run
``svn resolved''.