Re: Git Clone Parameter

[Junio C Hamano <gitster@pobox.com>]

"Philip Oakley" <philipoakley@iee.org> writes:

>> Allan Acheampong <allanadjei@gmail.com> writes:
>>
>>> ... I'm new to git, but I found it very
>>> confusing to understand the difference between "remote" ,
>>> "remotes". Is it in the cloned repo, or is it in a remote place?
>>> If its local, why doesn't it get shown when I do 'git branch' but
>>> when I do 'git branch -a'.
>
> For the uninitiated, the lack of distinct terminology can cause no end
> of confusion as most explanations presume that you will implicitly
> understand the context, which can't be true for such newbies.

True.

 * You work in a local repository.

 * You interact with repositories other than the local repository.
   Here, "to interact" mean "exchange the history with", either by
   pushing the commits in the local repository to the other one(s),
   or fetching the commits in the other one(s) to the local
   repository.

   These "other repositories" are "remote repositories" from the
   point of view of the local repository.

   Note that you may have two repositories you use for working on
   the same project, one on your desktop and one on your notebook.
   As far as the repository on your notebook is concerned, the
   repository on your desktop, if you interact with it from the
   repository on your notebook, is a "remote repository" (and the
   one on the desktop views the one on the notebook as "remote").

 * Often we call a "remote repository" just a "remote".  Especially
   when we give a convenience short-name to it, like "origin".

 * When you "clone" from a repository to create a "copy" to work in,
   from that new repository's point of view, the original repository
   is a "remote repository", and "git clone" configures things in
   the new repository so that you can conveniently interact with
   that original repository.  The last part is what lets you say
   "git fetch origin", for example, to interact with the "origin"
   remote.

 * Branches are local to each repository.  It is merely a social
   convention that the primary branch in the repository you cloned
   from (i.e. your "origin") is often called 'master', the primary
   branch in the local repository is called 'master', and you often
   interact with the history of the 'master' branch of the "origin"
   when you are on your 'master' branch.  There is no stronger tie
   between their 'master' and your 'master' other than the social
   convention, but Git makes it easier for you to work that way by
   setting a few configuration variables.

 * Some of the social conventions, and the configuration Git sets up
   to let you follow them easily, allows you to find out where the
   tips of branches at your remotes were, when you last observed
   them (remember, Git is distributed, so you do not ask "right
   now"; instead you have "when you last observed" and "make an
   observation right now" separately).  This is achieved by keeping
   the record of the last observation in "remote-tracking branches".

   The last observed value of the 'master' branch of the remote
   repository "origin" is stored as 'origin/master' (its full name
   is 'refs/remotes/origin/master', but you rarely have to spell it
   out) remote-tracking branch.

   CAVEAT: some older documentation call a "remote-tracking branch"
   just "remote branch", but we have been trying to move away from
   that practice, as it is confusing, because the 'master' branch at
   the 'origin' remote is often called a 'remote branch'.  When you
   see 'remote branch', you need to make sure which one the writer
   meant.

 * "git fetch" (and "git pull", which internally invokes "git
   fetch") is a way to "make the observation now".  "git fetch
   origin" updates your remote-tracking branches for the "origin".

 * "git pull" (and "git pull --rebase") is a way to do the "fetch"
   above and then integrate the history of the branch at the remote
   (which now you know its latest state, because you just observed
   it) with the history you have on your branch.  Again, these
   branches may be named 'master' but the user needs to be aware
   that they are two separate branches (your 'master' branch is just
   as a different entity from the 'master' branch of the remote
   repository as it is your 'next' or any other branch).

   To make it easier to work, git configures the history of which
   branch you obtained/observed from what remote is to be integrated
   with your history per your local branch.  Immediately after "git
   clone", you will typically have your 'master' branch, and the
   branch "knows" that it wants to integrate with the 'master'
   branch at 'origin' remote.  So "git pull" becomes:

    - "git fetch origin", because you will integrate with the
      history that comes from that remote, not other remotes;

    - which updates 'origin/master' remote-tracking branch, and
      possibly other remote-tracking branches under 'origin/'; and

    - integrate your branch with the history of 'origin/master'
      remote-tracking branch.

   We say "your 'master' branch is set to integrate with
   remote-tracking branch 'origin/master'".  It is morally
   equivalent to say "your 'master' branch integrates with the
   'master' branch of 'origin'".

  CAVEAT: people often call this relationship between your 'master'
  branch and 'origin/master' (or the 'master' branch of 'origin'
  remote) "tracking", e.g. "your 'master' branch tracks
  'origin/master'".  Unfortunately, this is a confusing misnomer, as
  the relationship between the 'master' branch of 'origin' and the
  remote-tracking branch 'orign/master' you have in your local
  repository is also called "tracking" (the latter keeps track of
  the former).  You are better off avoid using the word "track" for
  this purose, unless it is very clear from the context.