Skip to content

Minor tweaks and rewording to "The Refspec" section. #921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 6, 2017
Merged

Minor tweaks and rewording to "The Refspec" section. #921

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions book/10-git-internals/sections/refspec.asc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
=== The Refspec

Throughout this book, we've used simple mappings from remote branches to local references, but they can be more complex.
Suppose you add a remote like this:
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:

[source,console]
----
$ git remote add origin https://github.com/schacon/simplegit-progit
----

Running the above adds a section to your `.git/config` file, specifying the name of the remote (`origin`), the URL of the remote repository, and the refspec for fetching:
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:

[source,ini]
----
Expand All @@ -18,11 +18,11 @@ Running the above adds a section to your `.git/config` file, specifying the name
fetch = +refs/heads/*:refs/remotes/origin/*
----

The format of the refspec is an optional `+`, followed by `<src>:<dst>`, where `<src>` is the pattern for references on the remote side and `<dst>` is where those references will be written locally.
The format of the refspec is, first, an optional `+`, 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 `+` 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` 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
So, if there is a `master` branch on the server, you can access the log of that branch locally via any of the following:

[source,console]
----
Expand All @@ -33,16 +33,16 @@ $ git log refs/remotes/origin/master

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
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:

[source]
----
fetch = +refs/heads/master:refs/remotes/origin/master
----

This is just the default refspec for `git fetch` for that remote.
If you want to do something one time, you can specify the refspec on the command line, too.
To pull the `master` branch on the remote down to `origin/mymaster` locally, you can run
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:

[source,console]
----
Expand All @@ -61,11 +61,11 @@ From git@github.com:schacon/simplegit
* [new branch] topic -> origin/topic
----

In this case, the `master` branch pull was rejected because it wasn't a fast-forward reference.
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 `+` 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, add two lines:
If you want to always fetch the `master` and `experiment` branches from the `origin` remote, add two lines:

[source,ini]
----
Expand Down Expand Up @@ -130,3 +130,10 @@ $ git push origin :topic
----

Because the refspec is `<src>:<dst>`, by leaving off the `<src>` part, this basically says to make the `topic` branch on the remote nothing, which deletes it.

Or you can use the newer syntax (available since Git v1.7.0):

[source,console]
----
$ git push origin --delete topic
----