Define the full fmf identifier [fix #52]

docs/concept.rst

@@ -116,3 +116,56 @@ directory. Below you can see node names for different files:
     +-------------------------------+-----------------------+
     | wget/download/smoke.fmf       | /download/smoke       |
     +-------------------------------+-----------------------+
+
+
+Identifiers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Node names are unique across the metadata tree and thus can be
+used as identifiers for local referencing. In order to reference
+remote fmf nodes a full ``fmf identifier`` is defined as a
+dictionary containing keys with the following meaning:
+
+url
+    Git repository containing the metadata tree. Use any format
+    acceptable by the ``git clone`` command.
+ref
+    Branch, tag or commit specifying the desired git revision.
+    This is used to perform a ``git checkout`` in the repository.
+    By default the ``master`` branch is used.
+path
+    Path from the git repository root to the metadata tree root.
+    By default ``/`` is used as very often the fmf metadata root
+    is aligned with the git repository root.
+name
+    Node name as defined by the hierarchy in the metadata tree.
+
+Here's a full fmf identifier example::
+
+    url: https://github.com/psss/fmf
+    ref: 0.10
+    path: /examples/wget
+    name: /download/test
+
+Use default values for ``ref`` and ``path`` to reference the
+latest version of the smoke plan from the ``master`` branch::
+
+    url: https://github.com/psss/fmf
+    name: /plans/smoke
+
+If desired, it is also possible to write the identifier on a
+single line as supported by the ``yaml`` format::
+
+    {url: "https://github.com/psss/fmf", name: "/plans/smoke"}
+
+Let's freeze the stable test version by using a specific commit::
+
+    url: https://github.com/psss/fmf
+    ref: f24ef3f
+    name: /tests/basic/filter
+
+Reference a smoke plan from the ``master`` branch of another
+repository on the local filesystem::
+
+    url: file:///home/psss/git/tmt
+    name: /plans/smoke