.. _Step-Source-Common:

Common Parameters of source checkout operations
+++++++++++++++++++++++++++++++++++++++++++++++

All source checkout steps accept some common parameters to control how they get the sources and where they should be placed.
The remaining per-VC-system parameters are mostly to specify where exactly the sources are coming from.

``mode``
``method``

    These two parameters specify the means by which the source is checked out.
    ``mode`` specifies the type of checkout and ``method`` tells about the way to implement it.

    .. code-block:: python

        from buildbot.plugins import steps

        factory = BuildFactory()
        factory.addStep(steps.Mercurial(repourl='path/to/repo', mode='full',
                                        method='fresh'))

    The ``mode`` parameter a string describing the kind of VC operation that is desired (defaults to ``incremental``).
    The options are:

    ``incremental``
        Update the source to the desired revision, but do not remove any other files generated by previous builds.
        This allows compilers to take advantage of object files from previous builds.
        This mode is exactly same as the old ``update`` mode.

    ``full``
        Update the source, but delete remnants of previous builds.
        Build steps that follow will need to regenerate all object files.

    Methods are specific to the VC system in question, as they may take advantage of special behaviors in that VC system that can make checkouts more efficient or reliable.

``workdir``
    Like all Steps, this indicates the directory where the build will take place.
    Source Steps are special in that they perform some operations outside of the workdir (like creating the workdir itself).

``alwaysUseLatest``
    If True, bypass the usual behavior of checking out the revision in the source stamp, and always update to the latest revision in the repository instead.
    If the specific VC system supports branches and a specific branch is specified in the step parameters via ``branch`` or ``defaultBranch``, then the latest revision on that branch is checked out.

``retry``
    If set, this specifies a tuple of ``(delay, repeats)`` which means that when a full VC checkout fails, it should be retried up to ``repeats`` times, waiting ``delay`` seconds between the attempts.
    If you don't provide this, it defaults to ``None``, which means VC operations should not be retried.
    This is provided to make life easier for workers which are stuck behind poor network connections.

``repository``
    The name of this parameter might vary depending on the Source step you are running.
    The concept explained here is common to all steps and applies to ``repourl`` as well as for ``baseURL`` (when applicable).

    A common idiom is to pass ``Property('repository', 'url://default/repo/path')`` as repository.
    This grabs the repository from the source stamp of the build.
    This can be a security issue, if you allow force builds from the web, or have the :class:`WebStatus` change hooks enabled; as the worker will download code from an arbitrary repository.

``codebase``
    This specifies which codebase the source step should use to select the right source stamp.
    The default codebase value is ``''``.
    The codebase must correspond to a codebase assigned by the :bb:cfg:`codebaseGenerator`.
    If there is no codebaseGenerator defined in the master, then codebase doesn't need to be set; the default value will match all changes.

``timeout``
    Specifies the timeout for worker-side operations, in seconds.
    If your repositories are particularly large, then you may need to increase this value from the default of 1200 (20 minutes).

``logEnviron``
    If this option is true (the default), then the step's logfile will describe the environment variables on the worker.
    In situations where the environment is not relevant and is long, it may be easier to set ``logEnviron=False``.

``env``
    A dictionary of environment strings which will be added to the child command's environment.
    The usual property interpolations can be used in environment variable names and values - see :ref:`Properties`.
