10.5 Git Internals - The Refspec

Throughout this book, we’ve used simple mappings from remote branches to local references, but they can be more complex. Suppose you were following along with the last couple sections and had created a small local Git repository, and now wanted to add a remote to it:

Running the command above adds a section to your repository’s .git/config file, specifying the name of the remote (origin), the URL of the remote repository, and the refspec to be used for fetching:

The format of the refspec is, first, an optional {plus}, followed by <src>:<dst>, where <src> is the pattern for references on the remote side and <dst> is where those references will be tracked locally. The {plus} tells Git to update the reference even if it isn’t a fast-forward.

In the default case that is automatically written by a git remote add origin command, Git fetches all the references under refs/heads/ on the server and writes them to refs/remotes/origin/ locally. So, if there is a master branch on the server, you can access the log of that branch locally via any of the following:

They’re all equivalent, because Git expands each of them to refs/remotes/origin/master.

If you want Git instead to pull down only the master branch each time, and not every other branch on the remote server, you can change the fetch line to refer to that branch only:

This is just the default refspec for git fetch for that remote. If you want to do a one-time only fetch, you can specify the specific refspec on the command line, too. To pull the master branch on the remote down to origin/mymaster locally, you can run:

You can also specify multiple refspecs. On the command line, you can pull down several branches like so:

In this case, the master branch pull was rejected because it wasn’t listed as a fast-forward reference. You can override that by specifying the {plus} in front of the refspec.

You can also specify multiple refspecs for fetching in your configuration file. If you want to always fetch the master and experiment branches from the origin remote, add two lines:

You can’t use partial globs in the pattern, so this would be invalid:

However, you can use namespaces (or directories) to accomplish something like that. If you have a QA team that pushes a series of branches, and you want to get the master branch and any of the QA team’s branches but nothing else, you can use a config section like this:

If you have a complex workflow process that has a QA team pushing branches, developers pushing branches, and integration teams pushing and collaborating on remote branches, you can namespace them easily this way.