<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{Help Topic: The SVN Status Command}
\vspace{0.1in}
\labcourse{Understanding Your Tree Status and useful Aliases}
\vspace{0.2in}
\labdate{Spring 2021}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labline
\end{labcover}

\wikidoc{file=Help.SVNStatus}
\wikidoc{auth=mikerb@mit.edu}

%====================================================================
\section*{The SVN \cmd{status} Command}
%====================================================================

The \cmd{svn status} command informs you about what has changed in
your local repository checkout compared to the moment you first
checked it out or last did an \cmd{update}. It does not compare it to
the contents of the svn server. For this reason \cmd{svn status} may
be invoked offline. This is a tool I find valuable for confirming what
exactly I may have done to my local checkout. This is important (a)
right before committing changes, and (b) for confirming that I have
the same checkout as a colleague working with the same revision
number.  More info on \cmd{svn status} can always be found by Googling
"Subversion book" and reading the full PDF online free, or just
typing \cmd{svn help status} anytime on the command line.

%---------------------------------------------------------------------
\subsection*{Basic usage of the svn \cmd{status} command}

The basic syntax for the svn \cmd{status} command is:

\vspace{0.05in}
\begin{consoleverb}
 $ svn status        (invoked somewhere within previously checked out tree)
\end{consoleverb}
\vspace{0.15in}

\noindent
The \cmd{svn status} does {\em not} require a network connection to the
server and only indicates changes compared to your initial checkout or 
previous update. 

%---------------------------------------------------------------------
\subsection*{Deciphering the output of the svn \cmd{status} command}

The \cmd{svn status} output may look something like the below by way
of example:

\vspace{0.1in}
\begin{consoleverb}
 $ svn status
 M       Colors.cpp
 A       Fungo.cpp
 A       Fungo.h
 M       Items.cpp
 D       Mango.h
 ?       Utils.h
 ?       Utils.cpp
\end{consoleverb}
\vspace{0.1in}

\noindent
Files that have not been changed, deleted, or added or are any way
different compared to the last update are {\em not} reported. Otherwise
each line reports the file name, and how it is changed with the single
character on the left. In the example above, the output tells us:


\begin{packed_itemize}[1]
\item The files \var{Colors.cpp}  and \var{Items.cpp} are already known 
  to svn, but have been modified locally compared to the last update.

\item The files \var{Fungo.h} and \var{Fungo.cpp} have been
  newly added by you. Your local svn tree knows about them, but they
  they are not known on the remote svn server. They have been {\em
  scheduled} for addition the next time you do a commit of your local
  changes to the server.

\item The file \var{Mango.h} has been scheduled for deletion. It is gone 
  locally, but is still part of the official repository on the
  server. Your next commit will remove it on the server.

\item The files \var{Utils.h} and \var{Utils.cpp} are in your local 
  file system but they are completely unknown to svn. They were not
  part of the checkout or last update, and no action will be taken on
  them during the next commit. Possibly they should be rightfully
  ignored, or perhaps you have forgot to \cmd{svn add} them.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Generally you will encounter files having one of the above modes. There
are others however, and you can read about them in the svn documentation, 
or get a glimpse of them with \cmd{svn help status}.

%---------------------------------------------------------------------
\subsection*{Using the svn \cmd{status} command in quiet mode}

The \cmd{svn status} command may be used with the optional
argument, \cmd{--quiet}, or simply \cmd{-q}. This has the effect of
suppressing unversioned items. In the example above, you would get the
following output instead:

\vspace{0.1in}
\begin{consoleverb}
 $ svn -q status
 M       Colors.cpp
 A       Fungo.cpp
 A       Fungo.h
 M       Items.cpp
 D       Mango.h
\end{consoleverb}
\vspace{0.1in}

\noindent
The last two files, \var{Utils.h} and \var{Utils.cpp} are suppressed. The 
\var{--quiet} option is very useful when your local repository has many 
automatically generated files. This could include object files if
you're working in C++, or other temporary files if you're working with
LaTex for example.  In these cases the number of such lines can
overwhelm the output of the \cmd{svn status} command, rendering it
hard to use. 

%---------------------------------------------------------------------
\subsection*{Clever use of the svn \cmd{status} command in quiet mode}

While the \cmd{--quiet} option is useful in suppressing unversioned
files, sometimes those unversioned files are {\em supposed to be}
under version control. The \cmd{--quiet} option may prevent you from
noticing this. One common "gotcha" in groups of developers involves
one developer forgetting to add and check in a critical piece of
code. Things work fine on the first developer's machine, but are perhaps
broken on others' machines due to that missing piece of code.

\pskip

Here we describe a little hack using aliases, to get the best of both
worlds, the succinctness of the \cmd{--quiet} command and the verbosity
you need to catch critical files that are perhaps unintentionally 
unversioned.

\pskip

The below couple of aliases are simply shortcuts for invoking
the \cmd{svn status} command with and without the \cmd{--quiet}
option. It's not hard to type out these few words, but this alias
makes it very handy:

\vspace{0.1in}
\begin{fileverb}
 alias svns    'svn status'
 alias svnsq   'svn --quiet status'
\end{fileverb}
\vspace{0.1in}

\noindent
The next alias is where things get fun. We describe how this works,
but you can also just cut and paste this into your shell configuration
file.  The goal is to supress all unversioned files {\em except}
certain types. In the case below, the goal is to not supress C++
header and class files:

\vspace{0.1in}
\begin{fileverb}
 alias svns_h    'svns | grep "? " | grep .h'
 alias svns_cpp  'svns | grep "? " | grep .cpp'
 alias svnsm     'svnsq; svns_h; svns_cpp'
\end{fileverb}
\vspace{0.1in}

\noindent
The last alias, \cmd{svnsm}, is the only one I ever use. The previous
two, \cmd{svns\_h} and \cmd{svns\_cpp}, just help build up the definition 
of the third.  A few very common command line tricks are used
here. You can read up on them separately if they aren't familiar to
you:

\begin{packed_itemize}
\item Piping output: The output of one command line invocation can be 
  sent as input to another command line tool using the "pipe"
  utility. In the first line above, the output of "svns" is sent as
  input to the \cmd{grep} command, whose output is then sent as input
  to another invocation of \cmd{grep}.

\item The \cmd{grep} utility will filter given input, to produce only lines
  that contain a given pattern. In the example above, \cmd{grep "? "}
  only matches lines containing the 2-character string "? ", which
  should catch lines output from the \cmd{svn status} command for
  unversioned files. Of course we don't want {\em all} unversioned 
  files so we further filter on two file types, the \var{.h} and \var{.cpp}
  files.

\item The last little trick may be obvious. As on the last line, you can 
      build up an alias by chaining them together with a semicolon.
\end{packed_itemize}
The powerful command line tool \cmd{grep} is used to 

\end{document}

</pre></body></html>