From e652d7aa29a7baf81c41e0c63e8cfd0ea0f124ad Mon Sep 17 00:00:00 2001 From: Leative Date: Tue, 10 Nov 2020 15:12:50 +0100 Subject: [PATCH] Update remote-branches.asc The document differentiates between remote branches, remote-tracking branches and tracking branches. I tried to fix some ambiguities which could, in my opinion, be misleading. --- .../sections/remote-branches.asc | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/book/03-git-branching/sections/remote-branches.asc b/book/03-git-branching/sections/remote-branches.asc index 6885f322b..240d138be 100644 --- a/book/03-git-branching/sections/remote-branches.asc +++ b/book/03-git-branching/sections/remote-branches.asc @@ -24,7 +24,7 @@ Git also gives you your own local `master` branch starting at the same place as ==== Just like the branch name "`master`" does not have any special meaning in Git, neither does "`origin`". While "`master`" is the default name for a starting branch when you run `git init` which is the only reason it's widely used, "`origin`" is the default name for a remote when you run `git clone`. -If you run `git clone -o booyah` instead, then you will have `booyah/master` as your default remote branch.(((origin))) +If you run `git clone -o booyah` instead, then you will have `booyah/master` as your default remote-tracking branch.(((origin))) ==== .Server and local repositories after cloning @@ -42,7 +42,7 @@ This command looks up which server "`origin`" is (in this case, it's `git.ourcom .`git fetch` updates your remote-tracking branches image::images/remote-branches-3.png[`git fetch` updates your remote references] -To demonstrate having multiple remote servers and what remote branches for those remote projects look like, let's assume you have another internal Git server that is used only for development by one of your sprint teams. +To demonstrate having multiple remote servers and what remote-tracking branches for those remote projects look like, let's assume you have another internal Git server that is used only for development by one of your sprint teams. This server is at `git.team1.ourcompany.com`. You can add it as a new remote reference to the project you're currently working on by running the `git remote add` command as we covered in <>. Name this remote `teamone`, which will be your shortname for that whole URL. @@ -98,7 +98,7 @@ The simplest is just to keep it in memory for a few minutes, which you can easil For more information on the various credential caching options available, see <>. ==== -The next time one of your collaborators fetches from the server, they will get a reference to where the server's version of `serverfix` is under the remote branch `origin/serverfix`: +The next time one of your collaborators fetches from the server, they will get a reference to where the server's version of `serverfix` is under the remote-tracking branch `origin/serverfix`: [source,console] ---- @@ -131,7 +131,7 @@ This gives you a local branch that you can work on that starts where `origin/ser (((branches, tracking)))(((branches, upstream))) Checking out a local branch from a remote-tracking branch automatically creates what is called a "`tracking branch`" (and the branch it tracks is called an "`upstream branch`"). -Tracking branches are local branches that have a direct relationship to a remote branch. +Tracking branches are local branches that have a direct relationship to a remote branch via its respective remote-tracking branch. If you're on a tracking branch and type `git pull`, Git automatically knows which server to fetch from and which branch to merge in. When you clone a repository, it generally automatically creates a `master` branch that tracks `origin/master`. @@ -167,7 +167,7 @@ Switched to a new branch 'sf' Now, your local branch `sf` will automatically pull from `origin/serverfix`. -If you already have a local branch and want to set it to a remote branch you just pulled down, or want to change the upstream branch you're tracking, you can use the `-u` or `--set-upstream-to` option to `git branch` to explicitly set it at any time. +If you already have a local branch and want it to track a remote branch you just fetched, or want to change the upstream branch you're tracking, you can use the `-u` or `--set-upstream-to` option to `git branch` to explicitly specify the tracked remote branch via its local remote-tracking branch. [source,console] ---- @@ -194,14 +194,14 @@ $ git branch -vv testing 5ea463a Try something new ---- -So here we can see that our `iss53` branch is tracking `origin/iss53` and is "`ahead`" by two, meaning that we have two commits locally that are not pushed to the server. +So here we can see that our `iss53` branch is tracking `origin/iss53` and is "`ahead`" by two, meaning that we have two commits locally that are not yet pushed to the server. We can also see that our `master` branch is tracking `origin/master` and is up to date. -Next we can see that our `serverfix` branch is tracking the `server-fix-good` branch on our `teamone` server and is ahead by three and behind by one, meaning that there is one commit on the server we haven't merged in yet and three commits locally that we haven't pushed. +Next we can see that our `serverfix` branch is tracking the `server-fix-good` branch on our `teamone` server and is ahead by three and behind by one, meaning that there is one commit on the remote-tracking branch we haven't merged in yet and there are three commits locally that we haven't pushed. Finally we can see that our `testing` branch is not tracking any remote branch. -It's important to note that these numbers are only since the last time you fetched from each server. -This command does not reach out to the servers, it's telling you about what it has cached from these servers locally. -If you want totally up to date ahead and behind numbers, you'll need to fetch from all your remotes right before running this. +It's important to note that these numbers are only calculated against the remote-tracking branches which reflect the state at the last time you fetched from each server. +The above command does not reach out to the servers but merely considers what is cached from them locally. +If you want totally up to date ahead and behind numbers, you'll need to fetch from all your remotes right before running it. You could do that like this: [source,console]