2.2 How Git Stores Branches and Their Copies

So how does Git work?¹

A repository consists of a collection of branches. Each branch represents the history of a collection of files and directories (a file tree). Each combined set of changes to this collection (files and directories added or deleted, and/or file contents changed) is termed a commit.

When you first create a local copy of a remote repository (“clone the repo”), Git copies all of the original repository’s branches to your local system. The original remote repository is referred to as being upstream, and your local repo is downstream from it. Git distinguishes branches from the upstream repo by prefixing their names with ‘origin/’. Let’s draw some pictures. Figure 2.1 represents the state of the repo on Savannah:

+======================+
|       Branches       |
+======================+
| master               |
+----------------------+
| gawk-4.1-stable      |
+----------------------+
| gawk-4.0-stable      |
+----------------------+
| feature/fix-comments |
+----------------------+
| ...                  |
+----------------------+

After you clone the repo, on your local system you will have a single branch named master that’s visible when you use ‘git branch’ to see your branches.

$ git clone http://git.savannah.gnu.org/r/gawk.git  Clone the repo
$ cd gawk                                           Change to local copy
$ git branch                                        See branch information
-| * master

The current branch is always indicated with a leading asterisk (‘*’).

Pictorially, the local repo looks like Figure 2.2 (you can ignore the ‘T’ column for the moment):

+===+======================++=============================+
| T |    Local Branches    ||      Remote Branches        |
+===+======================++=============================+
| X | master               || origin/master               |
+---+----------------------++-----------------------------+
|   |                      || origin/gawk-4.1-stable      |
+---+----------------------++-----------------------------+
|   |                      || origin/gawk-4.0-stable      |
+---+----------------------++-----------------------------+
|   |                      || origin/feature/fix-comments |
+---+----------------------++-----------------------------+
|   |                      || ...                         |
+---+----------------------++-----------------------------+

Note that what is simply gawk-4.1-stable in the upstream repo is now referred to as origin/gawk-4.1-stable. The ‘origin/’ branches are a snapshot of the state of the upstream repo. This is how Git allows you to see what changes you’ve made with respect to the upstream repo, without having to actually communicate with the upstream repo over the Internet. (When files are identical, Git is smart enough to not have two separate physical copies on your local disk.)

If you’re working on a simple bug fix or change, you can do so directly in your local master branch. You can then commit your changes, and if you have access rights, push them upstream to the Savannah repo. (However, there is a process to follow. Please read the rest of this Web page.)