<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 Git Status Command}
\vspace{0.1in}
\labcourse{Understanding Your Tree Status and useful Aliases}
\vspace{0.2in}
\labdate{Fall 2024}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Oscar Viquez, oviquezr@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labline
\end{labcover}

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

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

The \cmd{git 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 update via \cmd{git pull}. It does not
compare it to the contents of the Git server. For this reason
\cmd{git 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 right before committing changes, to ensure that the desired
changes are staged for the next commit. More info on \cmd{git status}
can always be found by Googling "Git book" and reading the full PDF online
free, or just typing \cmd{git help status} anytime on the command line.

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

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

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

\noindent
The \cmd{git 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 \cmd{git status} command}

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

\vspace{0.1in}
\begin{consoleverb}
 $ git status
 On branch main
 Your branch is up to date with 'origin/main'.

 Changes to be committed:
   (use "git restore --staged &lt;file&gt;..." to unstage)
   modified:   app1/app1.cpp
   new file:   app1/main.cpp

 Changes not staged for commit:
   (use "git add &lt;file&gt;..." to update what will be committed)
   (use "git restore &lt;file&gt;..." to discard changes in working directory)
   modified:   app1/app1.h

 Untracked files:
   (use "git add &lt;file&gt;..." to include in what will be committed)
   app2/app2.cpp
   app2/app2.h

\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, grouped by how it would affect the
repository. In the example above, the output tells us:


\begin{packed_itemize}[1]
\item The file \var{app1/app1.cpp} is already known to Git, and has
  been modified locally compared to the last update. The changes are
  staged for the next commit, where they will be written to the
  repository's history.

\item The file \var{app1/main.cpp} is new to Git, has been newly added
  by you, and will be written to the repository on the next commit.

\item The file \var{app1/app1.h} is already known to Git, but has
  been modified locally compared to the last update. The changes are
  not currently staged for commit.

\item The files \var{app2/app2.h} and \var{app2/app2.cpp} are in your local
  file system but they are completely unknown to Git. 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{git 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 git documentation,
or get a glimpse of them with \cmd{git help status}.

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

The \cmd{git status} command may be used with the optional argument,
\var{--untracked-files[=&lt;mode&gt;]}, or simply \var{-u[&lt;mode&gt;]}. This can be
used to manage the level of detail for unversioned items. The possible modes
are:

\begin{itemize}
  \item no: skip all untracked files and folders.
  \item normal: show all untracked files, and untracked directories.
  \item all: also show individual files contained within untracked directories.
\end{itemize}

\vspace{0.1in}
\noindent
If no mode is set, the default is \var{all}. In the example above, the
\cmd{-uno} option would produce the following output instead:

\vspace{0.1in}
\begin{consoleverb}
 $ git status -uno
 On branch main
 Your branch is up to date with 'origin/main'.

 Changes to be committed:
   (use "git restore --staged &lt;file&gt;..." to unstage)
   modified:   app1/app1.cpp
   new file:   app1/main.cpp

 Changes not staged for commit:
   (use "git add &lt;file&gt;..." to update what will be committed)
   (use "git restore &lt;file&gt;..." to discard changes in working directory)
   modified:   app1/app1.h

\end{consoleverb}
\vspace{0.1in}

\noindent
The last two files, \var{app2/app2.h} and \var{app2/app2.cpp} are suppressed.
The \var{-uno} option is very useful when your local repository has many
automatically generated files that are not already caught by the filters
in the .gitignore files in the repository. 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{git 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>