From: Yves Orton Date: Sat, 20 Dec 2008 14:08:16 +0000 (+0100) Subject: explain git status and stuff about remotes X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=39219fd358d77b4ca3b647d1ee7ea114f08104d7;p=p5sagit%2Fp5-mst-13.2.git explain git status and stuff about remotes --- diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 27b0342..05b1e1a 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 which will be configured to merge from the remote +tracking branch C. + 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 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 ..." to unstage) + # + # modified: pod/perlrepository.pod + # + # Changed but not updated: + # (use "git add ..." to update what will be committed) + # + # modified: pod/perlrepository.pod + # + # Untracked files: + # (use "git add ..." 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 which has not been pushed to the +C 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. + =head1 SUBMITTING A PATCH If you have a patch in mind for Perl, you should first get a copy of