explain git status and stuff about remotes

1 files changed, 83 insertions, 3 deletions

diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod
index 27b034292a..05b1e1a933 100644
--- a/pod/perlrepository.pod
+++ b/pod/perlrepository.pod
@@ -70,22 +70,58 @@ NOTE: there are symlinks set up so that the /gitroot is actually optional.
 
 Once you have changed into the repository directory, you can inspect it.
 
-The repository contains a few branches:
 
-  % git branch -a
+After a clone the repository will contain a single local branch, which
+will be the current branch as well, as indicated by the asterix.
+
+  % git branch
+  * blead
+
+Using the -a switch to branch will show the remote tracking branches in the
+repository:
+
+  % git branch -r
   * blead
     origin/HEAD
     origin/blead
   ...
 
+The branches that begin with "origin" correspond to the "git remote" that
+you cloned from. Each branch on the remote will be exactly tracked by theses
+branches. You should NEVER do work on these remote tracking branches. You only
+ever do work in a local branch. Local branches can be configured to automerge
+(on pull) from a designated remote tracking branch. This is the case with the
+default branch C<blead> which will be configured to merge from the remote
+tracking branch C<origin/blead>.
+
 You can see recent commits:
 
   % git log
 
-And pull new changes from the repository:
+And pull new changes from the repository, and update your local repository 
+(must be clean first)
 
   % git pull
 
+Assuming we are on the branch C<blead> immediately after a pull, this command
+would be more or less equivalent to:
+
+  % git fetch
+  % git merge origin/blead
+
+In fact if you want to update your local repository without touching your working
+directory you do:
+
+  % git fetch
+
+And if you want to update your remote tracking branches for all defined remotes
+simultaneously you do
+
+  % git remote update
+
+Neither of these last two commands will update your working directory, however
+both will update the repository.
+
 To switch to another branch:
 
   % git checkout origin/maint-5.8-dor
@@ -94,6 +130,50 @@ To switch back to blead:
 
   % git checkout blead
 
+=head2 FINDING OUT YOUR STATUS
+
+The most common git command you will use will probably be
+
+  % git status
+
+This command will produce as output a description of the current state of the 
+repository, including modified files and unignored untracked files, and in addition
+it will show things like what files have been staged for the next commit, 
+and usually some useful information about how to change things. For instance the 
+following:
+
+  $ git status
+  # On branch blead
+  # Your branch is ahead of 'origin/blead' by 1 commit.
+  #
+  # Changes to be committed:
+  #   (use "git reset HEAD <file>..." to unstage)
+  #
+  #       modified:   pod/perlrepository.pod
+  #
+  # Changed but not updated:
+  #   (use "git add <file>..." to update what will be committed)
+  #
+  #       modified:   pod/perlrepository.pod
+  #
+  # Untracked files:
+  #   (use "git add <file>..." to include in what will be committed)
+  #
+  #       deliberate.untracked
+
+This shows that there were changes to this document staged for commit, and
+that there were further changes in the working directory not yet staged. It
+also shows that there was an untracked file in the working directory, and as
+you can see shows how to change all of this. It also shows that there
+is one commit on the  working branch C<blead> which has not been pushed to the
+C<origin> remote yet.
+
+When in doubt, before you do anything else, check your status and read it 
+carefully, many questions are answered directly by the git status output.
+
+NOTE: that this output is also what you see as a template if you do not
+provide a message to c<git commit>.
+
 =head1 SUBMITTING A PATCH
 
 If you have a patch in mind for Perl, you should first get a copy of