Firstly, the commit bot can autofix various problems, so these problems only need to be checked on commit (to check that they have been fixed), not on upload (another good reason to use the commit queue!). Secondly, you can skip slow tests on upload and only run them on commit, if running these every time slows development too much, but this can result in problems only being caught at the last minute, and thus requiring last-minute changes after you think they're good to go.

Bypassing tests

To skip the scripts on upload, use the --bypass-hooks flag, as in:

To skip the scripts on commit, use --bypass-hooks and directly commit your change.

You should only do these if necessary, as the presubmit scripts are there for a reason, but they're not perfect.

If you have trouble with a presubmit script, it's preferable to fix it, rather than simply bypassing it. See depot_tools: sending patches for how to contribute.

Design

When you run gcl upload or gcl commit, gcl will look for all files named PRESUBMIT.py in folders enclosing the files in your change, up to the repository root.

For each such file, it will load the file into the Python interpreter and then call either the CheckChangeOnUpload or CheckChangeOnCommit function depending on whether you are calling [gcl upload] or [gcl commit].

The same applies to git-cl upload, git-cl dcommit and git-cl push.

Please note that presubmit scripts are a best-effort kind of thing; they do not prevent users from submitting without running the scripts, since one can always dcommit, and in fact there is a --bypass-hooks (formerly --no_presubmit) flag to gcl that skips presubmit checks. Further, since they use the local copy of the PRESUBMIT.py files, users must sync their repos before the latest presubmit checks will run when they upload or submit.

More subtly, presubmit scripts do not guarantee invariants: even if presubmit scripts pass prior to submission to CQ, once all changes land, the scripts may fail! This is because 2 changes may individually pass the tests, and the patches both apply cleanly together, but the combined change does not pass tests. Since presubmit/precommit scripts run at upload or at start of CQ steps, if two such changes are in the CQ at the same time, they can both pass, both be enqueued, and both land, at which point the tests start failing. A common example is change 1 adding a new test, and change 2 changing existing tests. After they both land, there is a new test in the old style (from change 1), which is out of sync with the new tests (from change 2).

Writing tests

To create a new test, either create a new PRESUBMIT.py script or edit an existing one, adding a new function for your test.

To check your changes, first commit locally (else git-cl will complain about the dirty tree), then:

To test the upload checks (i.e., to run CheckChangeOnUpload):

To test the submit checks (i.e., to run CheckChangeOnCommit):

The functions must match these method signatures. You do not need to define both functions if you're only interested in one type of event, and if you want to run the same tests in both events, just have them both call a single underlying function:

The input_api parameter is an object through which you can get information about the change. Using the output_api you can create result objects.

Both CheckChangeOnXXX functions must return a list or tuple of result objects, or an empty list or tuple if there is nothing to report. The types of result objects you may use are output_api.PresubmitError (a critical error), output_api.PresubmitPromptWarning (a warning the user must acknowledge before the command will continue) and output_api.PresubmitNotifyResult (a message that should be shown). Each takes a message parameter, and optional "items" and "long_text" parameters.

Version 2

Presubmit version 2 reduces some of the overhead of managing which checks are executed on upload and/or submit. To enable presubmit version 2, in the global scope of your presubmit script, define:

In presubmit version 2, you are not required to use CheckChangeOnUpload and CheckChangeOnCommit as your entry points. Any function that begins with the prefix Check will be executed, receiving input_api and output_api as its parameters. CheckXXX functions that end in Upload will only be executed on upload and CheckXXX functions that end in Commit will only be executed on commit. CheckXXX functions that do not end in either suffix will be executed at both upload and commit. The format of return values of CheckChangeOnXXX functions is the same as for CheckChangeOnUpload/CheckChangeOnCommit. This makes existing presubmit scripts backwards compatible with presubmit version 2 provided there are no functions in the global scope of the script that begin with Check.

InputApi

The input_api parameter is an object of type presubmit.InputApi; see class InputApi in presubmit_support.py for implementation.

This object can be used to transform from local to repository paths and vice versa, and to get information on the files in the change that are contained in the same directory as your PRESUBMIT.py file or subdirectories thereof.

The input_api.change object represents the change itself. Using this object you can retrieve the description of the change, any key-value pairs in the description (e.g. BUG=123), and details on all of the files in the change (not just the ones contained by the directory your PRESUBMIT.py file resides in).

An input_api.canned_checks object contains a set of ready-made checks that you can easily add to your presubmit script.

The os/os.path module is available as input_api.os_path, so you do not need to import this yourself.

Files in the API are represented by an AffectedFile object through which you can query the LocalPath(), ServerPath(), and the Action() being performed ('A', 'M' or 'D').

The input_api.is_committing attribute indicates whether the CL is being committed or just uploaded. This is particularly useful if you wish the same test to be run for both upload and committing, but with different behavior. A common pattern is to prompt a warning on upload, but an error on committing, which allows a CL to be uploaded and reviewed even if the test fails, but not committed (without dcommit). This can be done as follows:

Caveats

It is possible to run arbitrary Python code in the presubmit scripts. To avoid side effects and hard-to-debug errors, it is safest to run tests in subprocesses. The InputApi object provides various facilities to assist with this; see example below.

Details and Example

The most detailed documentation for the presubmit API is in its implementation code.

The canned checks are good examples of what you can do with the presubmit API.

An example simple file might be as follows:

A simple example of a custom command (call from CheckChangeOnUpload or CheckChangeOnCommit) is: