From d87d84141aaafe70bf270ad4ccd1d25d096efe11 Mon Sep 17 00:00:00 2001
From: David Shevitz <dshevitz@google.com>
Date: Fri, 4 Aug 2017 08:20:27 -0700
Subject: [PATCH] Add new concept topic on refs/for namespace

This topic is intended to provide more conceptual/in-depth information
for users. By adding this topic, we have something we can link to in
future how-to and tutorial topics, so we don't have to re-explain
what the refs/for namespace is each time.

This content for this topic originated from several other existing
topics. Those topics are still in place in the documentation. This
duplication is expected, until such a time as the Concepts section
is more complete.

Change-Id: I91cf6da1bdc1f8f53031ab2c0ac2a4c08fb4c0ff
---
 Documentation/concept-refs-for-namespace.txt | 72 ++++++++++++++++++++
 Documentation/index.txt                      |  1 +
 2 files changed, 73 insertions(+)
 create mode 100644 Documentation/concept-refs-for-namespace.txt

diff --git a/Documentation/concept-refs-for-namespace.txt b/Documentation/concept-refs-for-namespace.txt
new file mode 100644
index 0000000000..c8776ae1ae
--- /dev/null
+++ b/Documentation/concept-refs-for-namespace.txt
@@ -0,0 +1,72 @@
+= The refs/for namespace
+
+When pushing a new or updated commit to Gerrit, you push that commit using a
+link:https://www.kernel.org/pub/software/scm/git/docs/gitglossary.html#def_ref[reference],
+in the `refs/for` namespace. This reference must also define
+the target branch, such as `refs/for/[BRANCH_NAME]`.
+
+For example, to create a new change on the master branch, you would use the
+following command:
+
+....
+git push origin HEAD:refs/for/master
+....
+
+The `refs/for/[BRANCH_NAME]` syntax allows Gerrit to differentiate between
+commits that are pushed for review and commits that are pushed directly into
+the repository.
+
+Gerrit supports using either the full name or the short name for a branch. For
+instance, this command:
+
+....
+git commit
+git push origin HEAD:refs/for/master
+....
+
+is the same as:
+
+....
+git commit
+git push origin HEAD:refs/for/refs/heads/master
+....
+
+Gerrit uses the `refs/for/` prefix to map the concept of "Pushing for Review" to
+the git protocol. For the git client, it looks like every push goes to the same
+branch, such as `refs/for/master`.  In fact, for each commit pushed to this ref,
+Gerrit creates a new ref under a `refs/changes/` namespace, which Gerrit uses
+to track these commits. These references use the following format:
+
+....
+refs/changes/[CD]/[ABCD]/[EF]
+....
+
+Where:
+
+* [CD] is the last two digits of the change number
+* [ABCD] is the change number
+* [EF] is the patch set number
+
+For example:
+
+....
+refs/changes/20/884120/1
+....
+
+You can use the change reference to fetch its corresponding commit:
+
+....
+git fetch https://[GERRIT_SERVER_URL]/[PROJECT] refs/changes/[XX]/[YYYY]/[ZZ] \
+&& git checkout FETCH_HEAD
+....
+
+NOTE: The fetch command can be copied from the
+link:user-review-ui.html#download[download command] in the Change screen.
+
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/index.txt b/Documentation/index.txt
index 2910ce4ce8..70a6759baa 100644
--- a/Documentation/index.txt
+++ b/Documentation/index.txt
@@ -93,6 +93,7 @@
 . link:config-labels.html[Review Labels]
 . link:access-control.html[Access Controls]
 . link:concept-changes.html[Changes]
+. link:concept-refs-for-namespace.html[The refs/for Namespace]
 
 == Resources
 * link:licenses.html[Licenses and Notices]