1 files changed, 97 insertions, 0 deletions
diff --git a/doc/source/using_config.rst b/doc/source/using_config.rst
new file mode 100644
index 000000000..d02aaf3d4
--- /dev/null
+++ b/doc/source/using_config.rst
@@ -0,0 +1,97 @@
+
+.. _user_config:
+
+
+User configuration
+==================
+User configuration and preferences can be specified in a user provided
+configuration file, and usually also on the command line.
+
+Values specified in a user provided configuration file override the
+defaults, while command line options take precedence over any other
+specified configurations.
+
+
+Configuration file
+------------------
+Users can provide a configuration file to override parameters in
+the default configuration.
+
+Unless a configuration file is explicitly specified on the command line when
+invoking ``bst``, an attempt is made to load user specific configuration from
+``$XDG_CONFIG_HOME/buildstream.conf``. On most Linux based systems, the location
+will be ``~/.config/buildstream.conf``
+
+
+Project specific value
+----------------------
+The ``projects`` key can be used to specify project specific configurations,
+the supported configurations on a project wide basis are listed here.
+
+.. _config_artifacts:
+
+Artifact server
+~~~~~~~~~~~~~~~
+The project you build will often specify a :ref:`remote artifact cache
+<artifacts>` already, but you may want to specify extra caches. There are two
+ways to do this.  You can add one or more global caches:
+
+**Example**
+
+.. code:: yaml
+
+   artifacts:
+     url: https://artifacts.com/artifacts
+
+Caches listed there will be considered lower priority than those specified
+by the project configuration.
+
+You can also add project-specific caches:
+
+**Example**
+
+.. code:: yaml
+
+   projects:
+     project-name:
+       artifacts:
+         - url: https://artifacts.com/artifacts1
+         - url: ssh://user@artifacts.com/artifacts2
+           push: true
+
+Caches listed here will be considered higher priority than those specified
+by the project.
+
+If you give a list of URLs, earlier entries in the list will have higher
+priority than later ones.
+
+Strict build plan
+~~~~~~~~~~~~~~~~~
+The strict build plan option decides whether you want elements
+to rebuild when their dependencies have changed. This is enabled
+by default, but recommended to turn off in developer scenarios where
+you might want to build a large system and test it quickly after
+modifying some low level component.
+
+
+**Example**
+
+.. code:: yaml
+
+   projects:
+     project-name:
+       strict: False
+
+
+.. note::
+
+   It is always possible to override this at invocation time using
+   the ``--strict`` and ``--no-strict`` command line options.
+
+
+Default configuration
+---------------------
+The default BuildStream configuration is specified here for reference:
+
+  .. literalinclude:: ../../buildstream/data/userconfig.yaml
+     :language: yaml