Skip to content

Files

Latest commit

 

History

History
executable file
·
9028 lines (5612 loc) · 530 KB

reference.md

File metadata and controls

executable file
·
9028 lines (5612 loc) · 530 KB

Table of Contents

archive

Functions to work with archives.

archive.create

Creates an archive, possibly compressed, from a list of files.

archive.create(archive, files=None)

Parameters:

Parameter Description
archive Path

Expected path of the generated archive file.
files glob or NoneType

An optional glob to describe the list of file paths that are to be included in the archive. If not specified, all files under the current working directory will be included. Note, the original file path in the filesystem will be preserved when archiving it.

archive.extract

Extract the contents of the archive to a path.

archive.extract(archive, type="AUTO", destination_folder=None, paths=None)

Parameters:

Parameter Description
archive Path

The path to the archive file.
type string

The archive type. Supported types: AUTO, JAR, ZIP, TAR, TAR_GZ and TAR_XZ. AUTO will try to infer the archive type automatically.
destination_folder Path or NoneType

The path to extract the archive to. This defaults to the directory where the archive is located.
paths glob or NoneType

An optional glob that is used to filter the files extracted from the archive.

author

Represents the author of a change

Fields:

Name Description
email string

The email of the author
name string

The name of the author

Returned By:

Consumed By:

authoring

The authors mapping between an origin and a destination

authoring.allowed

Create a list for an individual or team contributing code.

authoring_class authoring.allowed(default, allowlist)

Parameters:

Parameter Description
default string

The default author for commits in the destination. This is used in squash mode workflows or when users are not on the list.
allowlist sequence of string

List of authors in the origin that are allowed to contribute code. The authors must be unique

Examples:

Only pass thru allowed users:
authoring.allowed(
    default = "Foo Bar <noreply@foobar.com>",
    allowlist = [
       "someuser@myorg.com",
       "other@myorg.com",
       "another@myorg.com",
    ],
)
Only pass thru allowed LDAPs/usernames:

Some repositories are not based on email but use LDAPs/usernames. This is also supported since it is up to the origin how to check whether two authors are the same.

authoring.allowed(
    default = "Foo Bar <noreply@foobar.com>",
    allowlist = [
       "someuser",
       "other",
       "another",
    ],
)

authoring.overwrite

Use the default author for all the submits in the destination. Note that some destinations might choose to ignore this author and use the current user running the tool (In other words they don't allow impersonation).

authoring_class authoring.overwrite(default)

Parameters:

Parameter Description
default string

The default author for commits in the destination

Example:

Overwrite usage example:

Create an authoring object that will overwrite any origin author with noreply@foobar.com mail.

authoring.overwrite("Foo Bar <noreply@foobar.com>")

authoring.pass_thru

Use the origin author as the author in the destination, no filtering.

authoring_class authoring.pass_thru(default)

Parameters:

Parameter Description
default string

The default author for commits in the destination. This is used in squash mode workflows or if author cannot be determined.

Example:

Pass thru usage example:
authoring.pass_thru(default = "Foo Bar <noreply@foobar.com>")

authoring_class

The authors mapping between an origin and a destination

Returned By:

Consumed By:

buildozer

Module for Buildozer-related functionality such as creating and modifying BUILD targets.

buildozer.cmd

Creates a Buildozer command. You can specify the reversal with the 'reverse' argument.

Command buildozer.cmd(forward, reverse=None)

Parameters:

Parameter Description
forward string

Specifies the Buildozer command, e.g. 'replace deps :foo :bar'
reverse string or NoneType

The reverse of the command. This is only required if the given command cannot be reversed automatically and the reversal of this command is required by some workflow or Copybara check. The following commands are automatically reversible:

  • add
  • remove (when used to remove element from list i.e. 'remove srcs foo.cc'
  • replace

buildozer.create

A transformation which creates a new build target and populates its attributes. This transform can reverse automatically to delete the target.

transformation buildozer.create(target, rule_type, commands=[], before='', after='')

Parameters:

Parameter Description
target string

Target to create, including the package, e.g. 'foo:bar'. The package can be '.' for the root BUILD file.
rule_type string

Type of this rule, for instance, java_library.
commands sequence of string or sequence of Command

Commands to populate attributes of the target after creating it. Elements can be strings such as 'add deps :foo' or objects returned by buildozer.cmd.
before string

When supplied, causes this target to be created before the target named by 'before'
after string

When supplied, causes this target to be created after the target named by 'after'

buildozer.delete

A transformation which is the opposite of creating a build target. When run normally, it deletes a build target. When reversed, it creates and prepares one.

transformation buildozer.delete(target, rule_type='', recreate_commands=[], before='', after='')

Parameters:

Parameter Description
target string

Target to delete, including the package, e.g. 'foo:bar'
rule_type string

Type of this rule, for instance, java_library. Supplying this will cause this transformation to be reversible.
recreate_commands sequence of string or sequence of Command

Commands to populate attributes of the target after creating it. Elements can be strings such as 'add deps :foo' or objects returned by buildozer.cmd.
before string

When supplied with rule_type and the transformation is reversed, causes this target to be created before the target named by 'before'
after string

When supplied with rule_type and the transformation is reversed, causes this target to be created after the target named by 'after'

buildozer.modify

A transformation which runs one or more Buildozer commands against a single target expression. See http://go/buildozer for details on supported commands and target expression formats.

transformation buildozer.modify(target, commands)

Parameters:

Parameter Description
target string or sequence of string

Specifies the target(s) against which to apply the commands. Can be a list.
commands sequence of string or sequence of Command

Commands to apply to the target(s) specified. Elements can be strings such as 'add deps :foo' or objects returned by buildozer.cmd.

Examples:

Add a setting to one target:

Add "config = ':foo'" to foo/bar:baz:

buildozer.modify(
    target = 'foo/bar:baz',
    commands = [
        buildozer.cmd('set config ":foo"'),
    ],
)
Add a setting to several targets:

Add "config = ':foo'" to foo/bar:baz and foo/bar:fooz:

buildozer.modify(
    target = ['foo/bar:baz', 'foo/bar:fooz'],
    commands = [
        buildozer.cmd('set config ":foo"'),
    ],
)

buildozer.print

Executes a buildozer print command and returns the output. This is designed to be used in the context of a transform

string buildozer.print(ctx, attr, target)

Parameters:

Parameter Description
ctx TransformWork

The TransformWork object
attr string

The attribute from the target rule to print.
target string

The target to print from.

change

A change metadata. Contains information like author, change message or detected labels

Fields:

Name Description
author author

The author of the change
date_time_iso_offset string

Return a ISO offset date time. Example: 2011-12-03T10:15:30+01:00'
first_line_message string

The message of the change
labels dict[string, string]

A dictionary with the labels detected for the change. If the label is present multiple times it returns the last value. Note that this is a heuristic and it could include things that are not labels.
labels_all_values dict[string, list of string]

A dictionary with the labels detected for the change. Note that the value is a collection of the values for each time the label was found. Use 'labels' instead if you are only interested in the last value. Note that this is a heuristic and it could include things that are not labels.
merge bool

Returns true if the change represents a merge
message string

The message of the change
original_author author

The author of the change before any mapping
ref string

Origin reference ref

ChangeMessage

Represents a well formed parsed change message with its associated labels.

Fields:

Name Description
first_line string

First line of this message
text string

The text description this message, not including the labels.

Returned By:

message.label_values

Returns a list of values associated with the label name.

list of string message.label_values(label_name)

Parameters:

Parameter Description
label_name string

The label name.

Changes

Data about the set of changes that are being migrated. Each change includes information like: original author, change message, labels, etc. You receive this as a field in TransformWork object for user defined transformations

Fields:

Name Description
current list of change

List of changes that will be migrated
migrated list of change

List of changes that where migrated in previous Copybara executions or if using ITERATIVE mode in previous iterations of this workflow.

checker

A checker to be run on arbitrary data and files

Consumed By:

Command

Buildozer command type

Returned By:

Consumed By:

compression

DEPRECATED. Use the archive module. Module for compression related starlark utilities

compression.unzip_path

DEPRECATED: Use archive.extract instead. Unzip the zipped source CheckoutPath and unzip it to the destination CheckoutPath

compression.unzip_path(source_path, destination_path, filter=None)

Parameters:

Parameter Description
source_path Path

the zipped file source
destination_path Path

the path to unzip to
filter glob or list of string or NoneType

A glob relative to the archive root that will restrict what files
from the archive should be extracted.

console

A console that can be used in skylark transformations to print info, warning or error messages.

console.error

Show an error in the log. Note that this will stop Copybara execution.

console.error(message)

Parameters:

Parameter Description
message string

message to log

console.info

Show an info message in the console

console.info(message)

Parameters:

Parameter Description
message string

message to log

console.progress

Show a progress message in the console

console.progress(message)

Parameters:

Parameter Description
message string

message to log

console.verbose

Show an info message in the console if verbose logging is enabled.

console.verbose(message)

Parameters:

Parameter Description
message string

message to log

console.warn

Show a warning in the console

console.warn(message)

Parameters:

Parameter Description
message string

message to log

core

Core functionality for creating migrations, and basic transformations.

Fields:

Name Description
console console

Returns a handle to the console object.
main_config_path string

Location of the config file. This is subject to change

Command line flags:

Name Type Description
--allow-empty-diff boolean If set to false, Copybara will not write to the destination if the exact same change is already pending in the destination. Currently only supported for git.github_pr_destination and git.gerrit_destination.
--commands-timeout duration Commands timeout. Example values: 30s, 20m, 1h, etc.
--config-root string Configuration root path to be used for resolving absolute config labels like '//foo/bar'
--console-file-flush-interval duration How often Copybara should flush the console to the output file. (10s, 1m, etc.)If set to 0s, console will be flushed only at the end. Example values: 30s, 20m, 1h, etc.
--console-file-path string If set, write the console output also to the given file path.
--debug-file-break string Stop when file matching the glob changes
--debug-metadata-break boolean Stop when message and/or author changes
--debug-transform-break string Stop when transform description matches
--diff-bin string Command line diff tool bin used in merge import. Defaults to diff3, but users can pass in their own diffing tools (along with requisite arg reordering)
--disable-reversible-check boolean If set, all workflows will be executed without reversible_check, overriding the workflow config and the normal behavior for CHANGE_REQUEST mode.
--dry-run boolean Run the migration in dry-run mode. Some destination implementations might have some side effects (like creating a code review), but never submit to a main branch.
--event-monitor list Eventmonitors to enable. These must be in the list of available monitors.
--force, --force-update boolean Force the migration even if Copybara cannot find in the destination a change that is an ancestor of the one(s) being migrated. This should be used with care, as it could lose changes when migrating a previous/conflicting change.
--info-list-only boolean When set, the INFO command will print a list of workflows defined in the file.
--labels immutableMap Additional flags. Can be accessed in feedback and mirror context objects via the cli_labels field. In core.workflow, they are accessible as labels, but with names uppercased and prefixed with FLAG_ to avoid name clashes with existing labels. I.e. --labels=label1:value1 will define a label FLAG_LABEL1Format: --labels=flag1:value1,flag2:value2 Or: --labels flag1:value1,flag2:value2
--noansi boolean Don't use ANSI output for messages
--nocleanup boolean Cleanup the output directories. This includes the workdir, scratch clones of Git repos, etc. By default is set to false and directories will be cleaned prior to the execution. If set to true, the previous run output will not be cleaned up. Keep in mind that running in this mode will lead to an ever increasing disk usage.
--noprompt boolean Don't prompt, this will answer all prompts with 'yes'
--output-limit int Limit the output in the console to a number of records. Each subcommand might use this flag differently. Defaults to 0, which shows all the output.
--output-root string The root directory where to generate output files. If not set, ~/copybara/out is used by default. Use with care, Copybara might remove files inside this root if necessary.
--patch-bin string Path for GNU Patch command
--repo-timeout duration Repository operation timeout duration. Example values: 30s, 20m, 1h, etc.
--squash boolean Override workflow's mode with 'SQUASH'. This is useful mainly for workflows that use 'ITERATIVE' mode, when we want to run a single export with 'SQUASH', maybe to fix an issue. Always use --dry-run before, to test your changes locally.
--validate-starlark string Starlark should be validated prior to execution, but this might break legacy configs. Options are LOOSE, STRICT
--version-selector-use-cli-ref boolean If command line ref is to used with a version selector, pass this flag to tell copybara to use it.
-v, --verbose boolean Verbose output.

core.action

Create a dynamic Skylark action. This should only be used by libraries developers. Actions are Starlark functions that receive a context, perform some side effect and return a result (success, error or noop).

dynamic.action core.action(impl, params={})

Parameters:

Parameter Description
impl callable

The Skylark function to call
params dict

The parameters to the function. Will be available under ctx.params

core.action_migration

Defines a migration that is more flexible/less-opinionated migration than core.workflow. Most of the users should not use this migration and instead use core.workflow for moving code. In particular core.workflow provides many helping functionality like version handling, ITERATIVE/SQUASH/CHANGE_REQUEST modes, --read-config-from-change dynamic config, etc.

These are the features that raw_migration provides:

  • Support for migrations that don't move source code (similar to feedback)
  • Support for migrations that talk to more than one origin/destination endpoits (Feature still in progress)
  • Custom management of versioning: For example moving non-linear/multiple versions (Instead of `core.workflow`, that moves source code in relation to the previous migrated code and is able to only track one branch).

core.action_migration(name, origin, endpoints, action, description=None, filesystem=False)

Parameters:

Parameter Description
name string

The name of the migration.
origin trigger

The trigger endpoint of the migration. Accessible as ctx.origin
endpoints structure

Zero or more endpoints that the migration will have access for read and/or write. This is a field that should be defined as:
<br> endpoint = struct(<br> some_endpoint = foo.foo_api(...configuration...),<br> other_endpoint = baz.baz_api(...configuration...),<br> )<br>
Then they will be accessible in the action as ctx.endpoints.some_endpoint and ctx.endpoints.other_endpoint
action unknown

The action to execute when the migration is triggered.
description string or NoneType

A description of what this workflow achieves
filesystem bool

If true, the migration provide access to the filesystem to the endpoints

core.autopatch_config

Describes in the configuration for automatic patch file generation

core.autopatch_config core.autopatch_config(header=None, suffix='.patch', directory_prefix='', directory='AUTOPATCHES', strip_file_names_and_line_numbers=False, strip_file_names=False, strip_line_numbers=False, paths=None)

Parameters:

Parameter Description
header string or NoneType

A string to include at the beginning of each patch file
suffix string

Suffix to use when saving patch files
directory_prefix string or NoneType

Directory prefix used to relativize filenames when writing patch files. E.g. if filename is third_party/foo/bar/bar.go and we want to write third_party/foo/AUTOPATCHES/bar/bar.go, the value for this field would be 'third_party/foo'
directory string or NoneType

Directory in which to save the patch files.
strip_file_names_and_line_numbers bool

When true, strip filenames and line numbers from patch files
strip_file_names bool

When true, strip filenames from patch files
strip_line_numbers bool

When true, strip line numbers from patch files
paths glob or list of string or NoneType

Only create patch files that match glob. Default is to match all files

core.convert_encoding

Change the encoding for a set of files

transformation core.convert_encoding(before, after, paths)

Parameters:

Parameter Description
before string

The expected encoding of the files before transformation. Charset should be in the format expected by https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html
after string

The encoding to convert to. Same format as 'before'
paths glob

The files to be deleted

Example:

ISO-8859-1 to UTF-8:

Convert some files from ISO-8859-1 to UTF-8

core.convert_encoding(
    before = 'ISO-8859-1',
    after = 'UTF-8',
    paths = glob(["foo/*.txt"]),
)

In this example, foo/one.txt encoding will be changed from ISO-8859-1 to UTF-8.

core.copy

Copy files between directories and renames files

transformation core.copy(before, after, paths=glob(["**"]), overwrite=False, regex_groups={})

Parameters:

Parameter Description
before string

The name of the file or directory to copy. If this is the empty string and 'after' is a directory, then all files in the workdir will be copied to the sub directory specified by 'after', maintaining the directory tree.
after string

The name of the file or directory destination. If this is the empty string and 'before' is a directory, then all files in 'before' will be copied to the repo root, maintaining the directory tree inside 'before'.
paths glob or list of string or NoneType

A glob expression relative to 'before' if it represents a directory. Only files matching the expression will be copied. For example, glob(["**.java"]), matches all java files recursively inside 'before' folder. Defaults to match all the files recursively.
overwrite bool

Overwrite destination files if they already exist. Note that this makes the transformation non-reversible, since there is no way to know if the file was overwritten or not in the reverse workflow.
regex_groups dict

A set of named regexes that can be used to match part of the file name. Copybara uses re2 syntax. For example {"x": "[A-Za-z]+"}

Examples:

Copy a directory:

Move all the files in a directory to another directory:

core.copy("foo/bar_internal", "bar")

In this example, foo/bar_internal/one will be copied to bar/one.

Copy using Regex:

Change a file extension:

core.copy(before = 'foo/${x}.txt', after = 'foo/${x}.md', regex_groups = { 'x': '.*'})

In this example, foo/bar/README.txt will be copied to foo/bar/README.md.

Copy with reversal:

Copy all static files to a 'static' folder and use remove for reverting the change

core.transform(
    [core.copy("foo", "foo/static", paths = glob(["**.css","**.html", ]))],
    reversal = [core.remove(glob(['foo/static/**.css', 'foo/static/**.html']))]
)

core.dynamic_feedback

Create a dynamic Skylark feedback migration. This should only be used by libraries developers

dynamic.action core.dynamic_feedback(impl, params={})

Parameters:

Parameter Description
impl callable

The Skylark function to call
params dict

The parameters to the function. Will be available under ctx.params

core.dynamic_transform

Create a dynamic Skylark transformation. This should only be used by libraries developers

transformation core.dynamic_transform(impl, params={})

Parameters:

Parameter Description
impl callable

The Skylark function to call
params dict

The parameters to the function. Will be available under ctx.params

Examples:

Create a dynamic transformation without parameters:

To define a simple dynamic transformation, you don't even need to use core.dynamic_transform. The following transformation sets the change's message to uppercase.

def test(ctx):
  ctx.set_message(ctx.message.upper())

After defining this function, you can use test as a transformation in core.workflow.

Create a dynamic transformation with parameters:

If you want to create a library that uses dynamic transformations, you probably want to make them customizable. In order to do that, in your library.bara.sky, you need to hide the dynamic transformation (prefix with '_') and instead expose a function that creates the dynamic transformation with the param:

def _test_impl(ctx):
  ctx.set_message(ctx.message + ctx.params['name'] + str(ctx.params['number']) + '\n')

def test(name, number = 2):
  return core.dynamic_transform(impl = _test_impl,
                           params = { 'name': name, 'number': number})

After defining this function, you can use test('example', 42) as a transformation in core.workflow.

core.fail_with_noop

If invoked, it will fail the current migration as a noop

dynamic.action core.fail_with_noop(msg)

Parameters:

Parameter Description
msg string

The noop message

core.feedback

Defines a migration of changes' metadata, that can be invoked via the Copybara command in the same way as a regular workflow migrates the change itself.

It is considered change metadata any information associated with a change (pending or submitted) that is not core to the change itself. A few examples:

  • Comments: Present in any code review system. Examples: GitHub PRs or Gerrit code reviews.
  • Labels: Used in code review systems for approvals and/or CI results. Examples: GitHub labels, Gerrit code review labels.
For the purpose of this workflow, it is not considered metadata the commit message in Git, or any of the contents of the file tree.

core.feedback(name, origin, destination, actions=[], action=None, description=None)

Parameters:

Parameter Description
name string

The name of the feedback workflow.
origin trigger

The trigger of a feedback migration.
destination endpoint_provider

Where to write change metadata to. This is usually a code review system like Gerrit or GitHub PR.
action unknown

An action to execute when the migration is triggered
description string or NoneType

A description of what this workflow achieves

core.filter_replace

Applies an initial filtering to find a substring to be replaced and then applies a mapping of replaces for the matched text.

filter_replace core.filter_replace(regex, mapping={}, group=Whole text, paths=glob(["**"]), reverse=regex)

Parameters:

Parameter Description
regex string

A re2 regex to match a substring of the file
mapping unknown

A mapping function like core.replace_mapper or a dict with mapping values.
group int or NoneType

Extract a regex group from the matching text and pass this as parameter to the mapping instead of the whole matching text.
paths glob or list of string or NoneType

A glob expression relative to the workdir representing the files to apply the transformation. For example, glob(["**.java"]), matches all java files recursively. Defaults to match all the files recursively.
reverse string or NoneType

A re2 regex used as reverse transformation

Examples:

Simple replace with mapping:

Simplest mapping

core.filter_replace(
    regex = 'a.*',
    mapping = {
        'afoo': 'abar',
        'abaz': 'abam'
    }
)
TODO replace:

This replace is similar to what it can be achieved with core.todo_replace:

core.filter_replace(
    regex = 'TODO\\((.*?)\\)',
    group = 1,
        mapping = core.replace_mapper([
            core.replace(
                before = '${p}foo${s}',
                after = '${p}fooz${s}',
                regex_groups = { 'p': '.*', 's': '.*'}
            ),
            core.replace(
                before = '${p}baz${s}',
                after = '${p}bazz${s}',
                regex_groups = { 'p': '.*', 's': '.*'}
            ),
        ],
        all = True
    )
)

core.format

Formats a String using Java's String.format.

string core.format(format, args)

Parameters:

Parameter Description
format string

The format string
args sequence

The arguments to format

core.latest_version

Selects the latest version that matches the format. Using --force in the CLI will force to use the reference passed as argument instead.

VersionSelector core.latest_version(format, regex_groups={})

Parameters:

Parameter Description
format string

The format of the version. If using it for git, it has to use the completerefspec (e.g. 'refs/tags/${n0}.${n1}.${n2}')
regex_groups dict

A set of named regexes that can be used to match part of the versions. Copybara uses re2 syntax. Use the following nomenclature n0, n1, n2 for the version part (will use numeric sorting) or s0, s1, s2 (alphabetic sorting). Note that there can be mixed but the numbers cannot be repeated. In other words n0, s1, n2 is valid but not n0, s0, n1. n0 has more priority than n1. If there are fields where order is not important, use s(N+1) where N ist he latest sorted field. Example {"n0": "[0-9]+", "s1": "[a-z]+"}

Examples:

Version selector for Git tags:

Example of how to match tags that follow semantic versioning

core.latest_version(
    format = "refs/tags/${n0}.${n1}.${n2}",    regex_groups = {
        'n0': '[0-9]+',        'n1': '[0-9]+',        'n2': '[0-9]+',    })
Version selector for Git tags with mixed version semantics with X.Y.Z and X.Y tagging:

Edge case example: we allow a '.' literal prefix for numeric regex groups.

core.latest_version(
    format = "refs/tags/${n0}.${n1}${n2}",    regex_groups = {
        'n0': '[0-9]+',        'n1': '[0-9]+',        'n2': '(.[0-9]+)?',    })

core.merge_import_config

Describes which paths merge_import mode should be applied

core.merge_import_config core.merge_import_config(package_path, paths=None, use_consistency_file=False, merge_strategy='DIFF3')

Parameters:

Parameter Description
package_path string

Package location (ex. 'google3/third_party/java/foo').
paths glob or list of string or NoneType

Glob of paths to apply merge_import mode, relative to package_path
use_consistency_file bool

When merging, if a consistency file exists, use it to construct the center of the 3-way merge. This can result in a more accurate merge in some cases, such as when the config file has changed since the last import.
merge_strategy string

The strategy to use for merging files. DIFF3 shells out to diff3 with the -m flag to perform a 3-way merge. PATCH_MERGE creates a patch file by diffing the baseline and destination files, and then applies the patch to the origin file.

core.move

Moves files between directories and renames files

transformation core.move(before, after, paths=glob(["**"]), overwrite=False, regex_groups={})

Parameters:

Parameter Description
before string

The name of the file or directory before moving. If this is the empty string and 'after' is a directory, then all files in the workdir will be moved to the sub directory specified by 'after', maintaining the directory tree.
after string

The name of the file or directory after moving. If this is the empty string and 'before' is a directory, then all files in 'before' will be moved to the repo root, maintaining the directory tree inside 'before'.
paths glob or list of string or NoneType

A glob expression relative to 'before' if it represents a directory. Only files matching the expression will be moved. For example, glob(["**.java"]), matches all java files recursively inside 'before' folder. Defaults to match all the files recursively.
overwrite bool

Overwrite destination files if they already exist. Note that this makes the transformation non-reversible, since there is no way to know if the file was overwritten or not in the reverse workflow.
regex_groups dict

A set of named regexes that can be used to match part of the file name. Copybara uses re2 syntax. For example {"x": "[A-Za-z]+"}

Examples:

Move a directory:

Move all the files in a directory to another directory:

core.move("foo/bar_internal", "bar")

In this example, foo/bar_internal/one will be moved to bar/one.

Move all the files to a subfolder:

Move all the files in the checkout dir into a directory called foo:

core.move("", "foo")

In this example, one and two/bar will be moved to foo/one and foo/two/bar.

Move a subfolder's content to the root:

Move the contents of a folder to the checkout root directory:

core.move("foo", "")

In this example, foo/bar would be moved to bar.

Move using Regex:

Change a file extension:

core.move(before = 'foo/${x}.txt', after = 'foo/${x}.md', regex_groups = { 'x': '.*'})

In this example, foo/bar/README.txt will be moved to foo/bar/README.md.

core.remove

Remove files from the workdir. This transformation is only meant to be used inside core.transform for reversing core.copy like transforms. For regular file filtering use origin_files exclude mechanism.

transformation core.remove(paths)

Parameters:

Parameter Description
paths glob

The files to be deleted

Examples:

Reverse a file copy:

Move all the files in a directory to another directory:

core.transform(
    [core.copy("foo", "foo/public")],
    reversal = [core.remove(glob(["foo/public/**"]))])

In this example, foo/one will be moved to foo/public/one.

Copy with reversal:

Copy all static files to a 'static' folder and use remove for reverting the change

core.transform(
    [core.copy("foo", "foo/static", paths = glob(["**.css","**.html", ]))],
    reversal = [core.remove(glob(['foo/static/**.css', 'foo/static/**.html']))]
)

core.rename

A transformation for renaming several filenames in the working directory. This is a simplified version of core.move() for just renaming filenames without needing to use regex_groups. Note that it doesn't rename directories, only regular files.

transformation core.rename(before, after, paths=glob(["**"]), overwrite=False, suffix=False)

Parameters:

Parameter Description
before string

The filepath or suffix to change
after string

A filepath or suffix to use as replacement
paths glob or list of string or NoneType

A glob expression relative to 'before' if it represents a directory. Only files matching the expression will be renamed. For example, glob(["**.java"]), matches all java files recursively inside 'before' folder. Defaults to match all the files recursively. Note that if reversible transformation is needed, the glob should match the filenames too in that case (or alternatively use an explicit reversal by using core.transformation().
overwrite bool

Overwrite destination files if they already exist. Note that this makes the transformation non-reversible, since there is no way to know if the file was overwritten or not in the reverse workflow.
suffix bool

By default before/after match whole path segments. e.g. before = "FOO" wouldn't match example/barFOO. Sometimes only part of the path name needs to be replaced, e.g. renaming extensions. When suffix is set to true, it will match partial parts of the path string.

Examples:

Rename files:

Rename all FOO files:

core.rename("FOO", "FOO.txt")

In this example, any FOO in any directory will be renamed to FOO.txt.

Rename extension:

Rename *.md files to *.txt files:

core.rename(".md", ".txt", suffix = True)

In this example, foo/bar.md will be renamed to foo/bar.txt.

Rename files only in certain paths:

Renaming files in certain paths:

core.rename("/FOO", "/FOO.txt", paths = glob(['dir1/**', 'dir2/**']))

In this example, dir1/FOO will be renamed to dir1/FOO.txt. Note that FOO files outside dir1 and dir2 won't be renamed

core.replace

Replace a text with another text using optional regex groups. This transformation can be automatically reversed.

transformation core.replace(before, after, regex_groups={}, paths=glob(["**"]), first_only=False, multiline=False, repeated_groups=False, ignore=[])

Parameters:

Parameter Description
before string

The text before the transformation. Can contain references to regex groups. For example "foo${x}text".

before can only contain 1 reference to each unique regex_group. If you require multiple references to the same regex_group, add repeated_groups: True.

If '$' literal character needs to be matched, '$$' should be used. For example '$$FOO' would match the literal '$FOO'. [Note this argument is a string. If you want to match a regular expression it must be encoded as a regex_group.]
after string

The text after the transformation. It can also contain references to regex groups, like 'before' field.
regex_groups dict

A set of named regexes that can be used to match part of the replaced text.Copybara uses re2 syntax. For example {"x": "[A-Za-z]+"}
paths glob or list of string or NoneType

A glob expression relative to the workdir representing the files to apply the transformation. For example, glob(["**.java"]), matches all java files recursively. Defaults to match all the files recursively.
first_only bool

If true, only replaces the first instance rather than all. In single line mode, replaces the first instance on each line. In multiline mode, replaces the first instance in each file.
multiline bool

Whether to replace text that spans more than one line.
repeated_groups bool

Allow to use a group multiple times. For example foo${repeated}/${repeated}. Note that this won't match "fooX/Y". This mechanism doesn't use backtracking. In other words, the group instances are treated as different groups in regex construction and then a validation is done after that.
ignore sequence

A set of regexes. If the entire content of any line (or file, if multiline is enabled) matches any expression in this set, then Copybara will not apply this transformation to any text there. Because ignore is matched against the entire line (or entire file under multiline), not just the parts that match before, the ignore regex can refer to text outside the span that would be replaced.

Examples:

Simple replacement:

Replaces the text "internal" with "external" in all java files

core.replace(
    before = "internal",
    after = "external",
    paths = glob(["**.java"]),
)
Simple replacement in a specific file:

Replaces the text "internal" with "external" in all java files

core.replace(
    before = "internal",
    after = "external",
    paths = ['foo/bar.txt'],
)
Append some text at the end of files:
core.replace(
   before = '${end}',
   after  = 'Text to be added at the end',
   multiline = True,
   regex_groups = { 'end' : '\\z'},
)
Append some text at the end of files reversible:

Same as the above example but make the transformation reversible

core.transform([
    core.replace(
       before = '${end}',
       after  = 'some append',
       multiline = True,
       regex_groups = { 'end' : r'\z'},
    )
],
reversal = [
    core.replace(
       before = 'some append${end}',
       after = '',
       multiline = True,
       regex_groups = { 'end' : r'\z'},
    )])
Replace using regex groups:

In this example we map some urls from the internal to the external version in all the files of the project.

core.replace(
        before = "https://some_internal/url/${pkg}.html",
        after = "https://example.com/${pkg}.html",
        regex_groups = {
            "pkg": ".*",
        },
    )

So a url like https://some_internal/url/foo/bar.html will be transformed to https://example.com/foo/bar.html.

Remove confidential blocks:

This example removes blocks of text/code that are confidential and thus shouldn'tbe exported to a public repository.

core.replace(
        before = "${x}",
        after = "",
        multiline = True,
        regex_groups = {
            "x": "(?m)^.*BEGIN-INTERNAL[\\w\\W]*?END-INTERNAL.*$\\n",
        },
    )

This replace would transform a text file like:

This is
public
 // BEGIN-INTERNAL
 confidential
 information
 // END-INTERNAL
more public code
 // BEGIN-INTERNAL
 more confidential
 information
 // END-INTERNAL

Into:

This is
public
more public code
Replace with ignore:

This example replaces go links that shouldn't be in a public repository with (broken link), but ignores any lines that contain bazelbuild/rules_go/, to avoid replacing file paths present in the text.

core.replace(
        before = "${x}",
        after = "(broken link)",
        regex_groups = {
            "x": "(go|goto)/[-/_#a-zA-Z0-9?]*(.md|)",
        },
        ignore = [".*bazelbuild/rules_go/.*"],
    )

This replace would transform a text file like:

public code
go/copybara ... public code
public code ... go/copybara
go/copybara ... foo/bazelbuild/rules_go/bar
foo/bazelbuild/rules_go/baz ... go/copybara

Into:

public code
(broken link) ... public code
public code ... (broken link)
go/copybara ... foo/bazelbuild/rules_go/bar
foo/bazelbuild/rules_go/baz ... go/copybara

Note that the go/copybara links on lines that matched the ignore regex were not replaced. The transformation ignored these lines entirely.

core.replace_mapper

A mapping function that applies a list of replaces until one replaces the text (Unless all = True is used). This should be used with core.filter_replace or other transformations that accept text mapping as parameter.

mapping_function core.replace_mapper(mapping, all=False)

Parameters:

Parameter Description
mapping sequence of transformation

The list of core.replace transformations
all bool

Run all the mappings despite a replace happens.

core.reverse

Given a list of transformations, returns the list of transformations equivalent to undoing all the transformations

list of transformation core.reverse(transformations)

Parameters:

Parameter Description
transformations sequence of transformation

The transformations to reverse

core.todo_replace

Replace Google style TODOs. For example TODO(username, othername).

transformation core.todo_replace(tags=['TODO', 'NOTE'], mapping={}, mode='MAP_OR_IGNORE', paths=glob(["**"]), default=None, ignore=None)

Parameters:

Parameter Description
tags sequence of string

Prefix tag to look for
mapping dict

Mapping of users/strings
mode string

Mode for the replace:

  • 'MAP_OR_FAIL': Try to use the mapping and if not found fail.
  • 'MAP_OR_IGNORE': Try to use the mapping but ignore if no mapping found.
  • 'MAP_OR_DEFAULT': Try to use the mapping and use the default if not found.
  • 'SCRUB_NAMES': Scrub all names from TODOs. Transforms 'TODO(foo)' to 'TODO'
  • 'USE_DEFAULT': Replace any TODO(foo, bar) with TODO(default_string)
paths glob or list of string or NoneType

A glob expression relative to the workdir representing the files to apply the transformation. For example, glob(["**.java"]), matches all java files recursively. Defaults to match all the files recursively.
default string or NoneType

Default value if mapping not found. Only valid for 'MAP_OR_DEFAULT' or 'USE_DEFAULT' modes
ignore string or NoneType

If set, elements within TODO (with usernames) that match the regex will be ignored. For example ignore = "foo" would ignore "foo" in "TODO(foo,bar)" but not "bar".

Examples:

Simple update:

Replace TODOs and NOTES for users in the mapping:

core.todo_replace(
  mapping = {
    'test1' : 'external1',
    'test2' : 'external2'
  }
)

Would replace texts like TODO(test1) or NOTE(test1, test2) with TODO(external1) or NOTE(external1, external2)

Scrubbing:

Remove text from inside TODOs

core.todo_replace(
  mode = 'SCRUB_NAMES'
)

Would replace texts like TODO(test1): foo or NOTE(test1, test2):foo with TODO:foo and NOTE:foo

Ignoring Regex Patterns:

Ignore regEx inside TODOs when scrubbing/mapping

core.todo_replace(
  mapping = { 'aaa' : 'foo'},
  ignore = 'b/.*'
)

Would replace texts like TODO(b/123, aaa) with TODO(b/123, foo)

core.transform

Groups some transformations in a transformation that can contain a particular, manually-specified, reversal, where the forward version and reversed version of the transform are represented as lists of transforms. The is useful if a transformation does not automatically reverse, or if the automatic reversal does not work for some reason.
If reversal is not provided, the transform will try to compute the reverse of the transformations list.

transformation core.transform(transformations, reversal=The reverse of 'transformations', name=None, ignore_noop=None, noop_behavior=NOOP_IF_ANY_NOOP)

Parameters:

Parameter Description
transformations sequence of transformation

The list of transformations to run as a result of running this transformation.
reversal sequence of transformation or NoneType

The list of transformations to run as a result of running this transformation in reverse.
name unknown

Optional string identifier to name this transform. This can be used for better output readability or with the --skip-transforms flag.
ignore_noop bool or NoneType

WARNING: Deprecated. Use noop_behavior instead.
In case a noop error happens in the group of transformations (Both forward and reverse), it will be ignored, but the rest of the transformations in the group will still be executed. If ignore_noop is not set, we will apply the closest parent's ignore_noop.
noop_behavior string or NoneType

How to handle no-op transformations:

  • 'IGNORE_NOOP': Any no-ops among the wrapped transformations are ignored.
  • 'NOOP_IF_ANY_NOOP': Throws an exception as soon as a single wrapped transformation is a no-op.
  • 'NOOP_IF_ALL_NOOP': Ignores no-ops from the wrapped transformations unless they all no-op, in which case an exception is thrown.

core.verify_match

Verifies that a RegEx matches (or not matches) the specified files. Does not transform anything, but will stop the workflow if it fails.

transformation core.verify_match(regex, paths=glob(["**"]), verify_no_match=False, also_on_reversal=False, failure_message=None)

Parameters:

Parameter Description
regex string

The regex pattern to verify. To satisfy the validation, there has to be atleast one (or no matches if verify_no_match) match in each of the files included in paths. The re2j pattern will be applied in multiline mode, i.e. '^' refers to the beginning of a file and '$' to its end. Copybara uses re2 syntax.
paths glob or list of string or NoneType

A glob expression relative to the workdir representing the files to apply the transformation. For example, glob(["**.java"]), matches all java files recursively. Defaults to match all the files recursively.
verify_no_match bool

If true, the transformation will verify that the RegEx does not match.
also_on_reversal bool

If true, the check will also apply on the reversal. The default behavior is to not verify the pattern on reversal.
failure_message unknown

Optional string that will be included in the failure message.

core.workflow

Defines a migration pipeline which can be invoked via the Copybara command.

Implicit labels that can be used/exposed:

  • COPYBARA_CONTEXT_REFERENCE: Requested reference. For example if copybara is invoked as copybara copy.bara.sky workflow master, the value would be master.
  • COPYBARA_LAST_REV: Last reference that was migrated
  • COPYBARA_CURRENT_REV: The current reference being migrated
  • COPYBARA_CURRENT_REV_DATE_TIME: Date & time for the current reference being migrated in ISO format (Example: "2011-12-03T10:15:30+01:00")
  • COPYBARA_CURRENT_MESSAGE: The current message at this point of the transformations
  • COPYBARA_CURRENT_MESSAGE_TITLE: The current message title (first line) at this point of the transformations
  • COPYBARA_AUTHOR: The author of the change

core.workflow(name, origin, destination, authoring, transformations=[], origin_files=glob([""]), destination_files=glob([""]), mode="SQUASH", reversible_check=True for 'CHANGE_REQUEST' mode. False otherwise, check_last_rev_state=False, ask_for_confirmation=False, dry_run=False, after_migration=[], after_workflow=[], change_identity=None, set_rev_id=True, smart_prune=False, merge_import=None, autopatch_config=None, after_merge_transformations=[], migrate_noop_changes=False, experimental_custom_rev_id=None, custom_rev_id=None, description=None, checkout=True, reversible_check_ignore_files=None, consistency_file_path=None)

Parameters:

Parameter Description
name string

The name of the workflow.
origin origin

Where to read from the code to be migrated, before applying the transformations. This is usually a VCS like Git, but can also be a local folder or even a pending change in a code review system like Gerrit.
destination destination

Where to write to the code being migrated, after applying the transformations. This is usually a VCS like Git, but can also be a local folder or even a pending change in a code review system like Gerrit.
authoring authoring_class

The author mapping configuration from origin to destination.
transformations sequence

The transformations to be run for this workflow. They will run in sequence.
origin_files glob or list of string or NoneType

A glob or list of files relative to the workdir that will be read from the origin during the import. For example glob(["**.java"]), all java files, recursively, which excludes all other file types, or ['foo.java'] for a specific file.
destination_files glob or list of string or NoneType

A glob relative to the root of the destination repository that matches files that are part of the migration. Files NOT matching this glob will never be removed, even if the file does not exist in the source. For example glob([''], exclude = ['/BUILD']) keeps all BUILD files in destination when the origin does not have any BUILD files. You can also use this to limit the migration to a subdirectory of the destination, e.g. glob(['java/src/'], exclude = ['/BUILD']) to only affect non-BUILD files in java/src.
mode string

Workflow mode. Currently we support four modes:

  • 'SQUASH': Create a single commit in the destination with new tree state.
  • 'ITERATIVE': Import each origin change individually.
  • 'CHANGE_REQUEST': Import a pending change to the Source-of-Truth. This could be a GH Pull Request, a Gerrit Change, etc. The final intention should be to submit the change in the SoT (destination in this case).
  • 'CHANGE_REQUEST_FROM_SOT': Import a pending change from the Source-of-Truth. This mode is useful when, despite the pending change being already in the SoT, the users want to review the code on a different system. The final intention should never be to submit in the destination, but just review or test
reversible_check bool or NoneType

Indicates if the tool should try to to reverse all the transformations at the end to check that they are reversible.
The default value is True for 'CHANGE_REQUEST' mode. False otherwise
check_last_rev_state bool

If set to true, Copybara will validate that the destination didn't change since last-rev import for destination_files. Note that this flag doesn't work for CHANGE_REQUEST mode.
ask_for_confirmation bool

Indicates that the tool should show the diff and require user's confirmation before making a change in the destination.
dry_run bool

Run the migration in dry-run mode. Some destination implementations might have some side effects (like creating a code review), but never submit to a main branch.
after_migration sequence

Run a feedback workflow after one migration happens. This runs once per change in ITERATIVE mode and only once for SQUASH.
after_workflow sequence

Run a feedback workflow after all the changes for this workflow run are migrated. Prefer after_migration as it is executed per change (in ITERATIVE mode). Tasks in this hook shouldn't be critical to execute. These actions shouldn't record effects (They'll be ignored).
change_identity string or NoneType

By default, Copybara hashes several fields so that each change has an unique identifier that at the same time reuses the generated destination change. This allows to customize the identity hash generation so that the same identity is used in several workflows. At least ${copybara_config_path} has to be present. Current user is added to the hash automatically.

Available variables:

  • ${copybara_config_path}: Main config file path
  • ${copybara_workflow_name}: The name of the workflow being run
  • ${copybara_reference}: The requested reference. In general Copybara tries its best to give a repetable reference. For example Gerrit change number or change-id or GitHub Pull Request number. If it cannot find a context reference it uses the resolved revision.
  • ${label:label_name}: A label present for the current change. Exposed in the message or not.
If any of the labels cannot be found it defaults to the default identity (The effect would be no reuse of destination change between workflows)
set_rev_id bool

Copybara adds labels like 'GitOrigin-RevId' in the destination in order to track what was the latest change imported. For CHANGE_REQUEST workflows it is not used and is purely informational. This field allows to disable it for that mode. Destinations might ignore the flag.
smart_prune bool

By default CHANGE_REQUEST workflows cannot restore scrubbed files. This flag does a best-effort approach in restoring the non-affected snippets. For now we only revert the non-affected files. This only works for CHANGE_REQUEST mode.
merge_import bool or core.merge_import_config or NoneType

A migration mode that shells out to a diffing tool (default is diff3) to merge all files. The inputs to the diffing tool are (1) origin file (2) baseline file (3) destination file. This can be used to perpetuate destination-only changes in non source of truth repositories.
autopatch_config core.autopatch_config or NoneType

Configuration that describes the setting for automatic patch file generation
after_merge_transformations sequence

Perform these transformations after merge_import, but before Copybara writes to the destination. Ex: any BUILD file generations that rely on the results of merge_import
migrate_noop_changes bool

By default, Copybara tries to only migrate changes that affect origin_files or config files. This flag allows to include all the changes. Note that it might generate more empty changes errors. In ITERATIVE mode it might fail if some transformation is validating the message (Like has to contain 'PUBLIC' and the change doesn't contain it because it is internal).
experimental_custom_rev_id string or NoneType

DEPRECATED(Remove by 2024/01/01: Use . Use this label name instead of the one provided by the origin.
custom_rev_id string or NoneType

If the destination uses labels to mark the last change migrated, use this label name instead of the one provided by the origin. This allows to to have two migrations to the same destination without the other migration changes interfering this migration. I can also serve to clearly state where the change is coming from.
description string or NoneType

A description of what this workflow achieves
checkout bool

Allows disabling the checkout. The usage of this feature is rare. This could be used to update a file of your own repo when a dependant repo version changes and you are not interested on the files of the dependant repo, just the new version.
reversible_check_ignore_files glob or list of string or NoneType

Ignore the files matching the glob in the reversible check
consistency_file_path string or NoneType

Under development. Must end with .bara.consistency

Command line flags:

Name Type Description
--baseline-for-merge-import string Origin baseline to use for merge import. This overrides any inferred origin baseline
--change-request-from-sot-limit int Number of origin baseline changes to use for trying to match one in the destination. It can be used if the are many parent changes in the origin that are a no-op in the destination
--change-request-from-sot-retry list Number of retries and delay between retries when we cannot find the baseline in the destination for CHANGE_REQUEST_FROM_SOT. For example '10,30,60' will retry three times. The first retry will be delayed 10s, the second one 30s and the third one 60s
--change-request-parent, --change_request_parent string Commit revision to be used as parent when importing a commit using CHANGE_REQUEST workflow mode. This shouldn't be needed in general as Copybara is able to detect the parent commit message.
--check-last-rev-state boolean If enabled, Copybara will validate that the destination didn't change since last-rev import for destination_files. Note that this flag doesn't work for CHANGE_REQUEST mode.
--default-author string Use this author as default instead of the one in the config file.Format should be 'Foo Bar foobar@example.com'
--diff-in-origin boolean When this flag is enabled, copybara will show different changes between last Revision and current revision in origin instead of in destination. NOTE: it Only works for SQUASH and ITERATIVE
--disable-consistency-merge-import boolean If merge import is set to use consistency in the config, disable it for this run. This uses an import baseline instead. A new consistency file will still be generated.
--force-author author Force the author to this. Note that this only changes the author before the transformations happen, you can still use the transformations to alter it.
--force-message string Force the change description to this. Note that this only changes the message before the transformations happen, you can still use the transformations to alter it.
--ignore-noop boolean Only warn about operations/transforms that didn't have any effect. For example: A transform that didn't modify any file, non-existent origin directories, etc.
--import-noop-changes boolean By default Copybara will only try to migrate changes that could affect the destination. Ignoring changes that only affect excluded files in origin_files. This flag disables that behavior and runs for all the changes.
--info-include-versions boolean Include upstream versions in the info command output.
--init-history boolean Import all the changes from the beginning of the history up to the resolved ref. For 'ITERATIVE' workflows this will import individual changes since the first one. For 'SQUASH' it will import the squashed change up to the resolved ref. WARNING: Use with care, this flag should be used only for the very first run of Copybara for a workflow.
--iterative-limit-changes int Import just a number of changes instead of all the pending ones
--last-rev string Last revision that was migrated to the destination
--nosmart-prune boolean Disable smart prunning
--notransformation-join boolean By default Copybara tries to join certain transformations in one so that it is more efficient. This disables the feature.
--read-config-from-change boolean For each imported origin change, load the workflow's origin_files, destination_files and transformations from the config version of that change. The rest of the fields (more importantly, origin and destination) cannot change and the version from the first config will be used.
--read-config-from-change-disable boolean --read-config-from-change is a arity 0 flag, this flag overrides it to override it being enabled.
--same-version boolean Re-import the last version imported. This is useful for example to check that a refactor in a copy.bara.sky file doesn't introduce accidental changes.
--skip-transforms list List of transform names that should be skipped.
--squash-skip-history boolean Avoid exposing the history of changes that are being migrated. This is useful when we want to migrate a new repository but we don't want to expose all the change history to metadata.squash_notes.
--threads int Number of threads to use when running transformations that change lot of files
--threads-for-merge-import int Number of threads to use for executing the diff tool for the merge import mode.
--threads-min-size int Minimum size of the lists to process to run them in parallel
--to-folder boolean Sometimes a user wants to test what the outcome would be for a workflow without changing the configuration or adding an auxiliary testing workflow. This flag allows to change an existing workflow to use folder.destination
--workflow-identity-user string Use a custom string as a user for computing change identity

core.autopatch_config

The configuration that describes automatic patch file generation

Returned By:

Consumed By:

credentials

Module for working with credentials.

credentials.static_secret

Holder for secrets that can be in plaintext within the config.

CredentialIssuer credentials.static_secret(name, secret)

Parameters:

Parameter Description
name string

A name for this secret.
secret string

The secret value.

credentials.static_value

Holder for credentials that are safe to read/log (e.g. 'x-access-token') .

CredentialIssuer credentials.static_value(value)

Parameters:

Parameter Description
value string

The open value.

credentials.toml_key_source

Supply an authentication credential from the file pointed to by the --http-credential-file flag.

CredentialIssuer credentials.toml_key_source(dot_path)

Parameters:

Parameter Description
dot_path string

Dot path to the data field containing the credential.

credentials.username_password

A pair of username and password credential issuers.

UsernamePasswordIssuer credentials.username_password(username, password)

Parameters:

Parameter Description
username CredentialIssuer

Username credential.
password CredentialIssuer

Password credential.

datetime

Module for datetime manipulation.

datetime.fromtimestamp

Returns a starlark_datetime object representation of the epoch time. The object is timezone aware.

StarlarkDateTime datetime.fromtimestamp(timestamp=0, tz='America/Los_Angeles')

Parameters:

Parameter Description
timestamp int

Epoch time in seconds.
tz string

The timezone. E.g. America/New_York, Asia/Tokyo, Europe/Rome, etc.

datetime.now

Returns a starlark_datetime object. The object is timezone aware.

StarlarkDateTime datetime.now(tz='America/Los_Angeles')

Parameters:

Parameter Description
tz string

The timezone. E.g. America/New_York, Asia/Tokyo, Europe/Rome

description_checker

A checker to be run on change descriptions

destination

A repository which a source of truth can be copied to

Returned By:

Consumed By:

destination_effect

Represents an effect that happened in the destination due to a single migration

Fields:

Name Description
destination_ref destination_ref

Destination reference updated/created. Might be null if there was no effect. Might be set even if the type is error (For example a synchronous presubmit test failed but a review was created).
errors list of string

List of errors that happened during the migration
origin_refs list of origin_ref

List of origin changes that were included in this migration
summary string

Textual summary of what happened. Users of this class should not try to parse this field.
type string

Return the type of effect that happened: CREATED, UPDATED, NOOP, INSUFFICIENT_APPROVALS or ERROR

destination_reader

Handle to read from the destination

Returned By:

destination_reader.copy_destination_files

Copy files from the destination into the workdir.

destination_reader.copy_destination_files(glob, path=None)

Parameters:

Parameter Description
glob glob or list of string or NoneType

Files to copy to the workdir, potentially overwriting files checked out from the origin.
path Path or NoneType

Optional path to copy the files to

Example:

Copy files from the destination's baseline:

This can be added to the transformations of your core.workflow:

def _copy_destination_file(ctx):
   content = ctx.destination_reader().copy_destination_files(glob(include = ['path/to/**']))

transforms = [core.dynamic_transform(_copy_destination_file)]

Would copy all files in path/to/ from the destination baseline to the copybara workdir. The files do not have to be covered by origin_files nor destination_files, but will cause errors if they are not covered by destination_files and not moved or deleted.

destination_reader.file_exists

Checks whether a given file exists in the destination.

bool destination_reader.file_exists(path)

Parameters:

Parameter Description
path string

Path to the file.

destination_reader.read_file

Read a file from the destination.

string destination_reader.read_file(path)

Parameters:

Parameter Description
path string

Path to the file.

Example:

Read a file from the destination's baseline:

This can be added to the transformations of your core.workflow:

def _read_destination_file(ctx):
    content = ctx.destination_reader().read_file(path = 'path/to/my_file.txt')
    ctx.console.info(content)

    transforms = [core.dynamic_transform(_read_destination_file)]

Would print out the content of path/to/my_file.txt in the destination. The file does not have to be covered by origin_files nor destination_files.

destination_ref

Reference to the change/review created/updated on the destination.

Fields:

Name Description
id string

Destination reference id
type string

Type of reference created. Each destination defines its own and guarantees to be more stable than urls/ids
url string

Url, if any, of the destination change

Returned By:

Consumed By:

dict

dict is a built-in type representing an associative mapping or dictionary. A dictionary supports indexing using d[k] and key membership testing using k in d; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to d[k] or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key.

d = {0: "x", 2: "z", 1: "y"}
[k for k in d]  # [0, 2, 1]
d.pop(2)
d[0], d[2] = "a", "b"
0 in d, "a" in d  # (True, False)
[(k, v) for k, v in d.items()]  # [(0, "a"), (1, "y"), (2, "b")]

There are four ways to construct a dictionary:

  1. A dictionary expression {k: v, ...} yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value.
  2. A dictionary comprehension {k: v for vars in seq} yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value. 
    {k: v for k, v in (("a", 0), ("b", 1), ("a", 2))}  # {"a": 2, "b": 1}
{i: 2*i for i in range(3)}  # {0: 0, 1: 2, 2: 4}
  3. A call to the built-in dict function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted.
  4. The union expression x | y yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key k in common, the right hand side dictionary's value of the key (in other words, y[k]) wins. The |= variant of the union operator modifies a dictionary in-place. Example:
    d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"}
# d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"}
d = {"a": 1, "b": 2}
d |= {"b": 3, "c": 4}
# d == {"a": 1, "b": 3, "c": 4}

Returned By:

Consumed By:

dict.clear

Remove all items from the dictionary.

dict.clear()

dict.get

Returns the value for key if key is in the dictionary, else default. If default is not given, it defaults to None, so that this method never throws an error.

unknown dict.get(key, default=None)

Parameters:

Parameter Description
key unknown

The key to look for.
default unknown

The default value to use (instead of None) if the key is not found.

dict.items

Returns the list of key-value tuples:

{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")]

sequence dict.items()

dict.keys

Returns the list of keys:

{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1]

sequence dict.keys()

dict.pop

Removes a key from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified default value; if no default value was specified, fail instead.

unknown dict.pop(key, default=unbound)

Parameters:

Parameter Description
key unknown

The key.
default unknown

a default value if the key is absent.

dict.popitem

Remove and return the first (key, value) pair from the dictionary. popitem is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the popitem call fails.

tuple dict.popitem()

dict.setdefault

If key is in the dictionary, return its value. If not, insert key with a value of default and return default. default defaults to None.

? dict.setdefault(key, default=None)

Parameters:

Parameter Description
key ?

The key.
default ?

a default value if the key is absent.

dict.update

Updates the dictionary first with the optional positional argument, pairs, then with the optional keyword arguments If the positional argument is present, it must be a dict, iterable, or None. If it is a dict, then its key/value pairs are inserted into this dict. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted. Each keyword argument name=value causes the name/value pair to be inserted into this dict.

dict.update(pairs=[], kwargs)

Parameters:

Parameter Description
pairs unknown

Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.
kwargs dict

Dictionary of additional entries.

dict.values

Returns the list of values:

{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"]

sequence dict.values()

dynamic.action_result

Result objects created by actions to tell Copybara what happened.

Fields:

Name Description
msg string

The message associated with the result
result string

The result of this action

Returned By:

endpoint

An origin or destination API in a feedback migration.

Fields:

Name Description
url string

Return the URL of this endpoint.

Returned By:

endpoint.new_destination_ref

Creates a new destination reference out of this endpoint.

destination_ref endpoint.new_destination_ref(ref, type, url=None)

Parameters:

Parameter Description
ref string

The reference.
type string

The type of this reference.
url string or NoneType

The url associated with this reference, if any.

endpoint.new_origin_ref

Creates a new origin reference out of this endpoint.

origin_ref endpoint.new_origin_ref(ref)

Parameters:

Parameter Description
ref string

The reference.

feedback.context

Gives access to the feedback migration information and utilities. This context is a concrete implementation for feedback migrations.

Fields:

Name Description
action_name string

The name of the current action.
cli_labels dict[string, string]

Access labels that a user passes through flag '--labels'. For example: --labels=foo:value1,bar:value2. Then it can access in this way:cli_labels['foo'].
console Console

Get an instance of the console to report errors or warnings
destination endpoint

An object representing the destination. Can be used to query or modify the destination state
endpoints structure

An object that gives access to the API of the configured endpoints
feedback_name string

DEPRECATED: The name of the Feedback migration calling this action. Use migration_name instead.
fs action.filesystem

If a migration of type core.action_migration sets filesystem = True, it gives access to the underlying migration filesystem to manipulate files.
migration_name string

The name of the migration calling this action.
origin endpoint

An object representing the origin. Can be used to query about the ref or modifying the origin state
params dict

Parameters for the function if created with core.action
refs list of string

A list containing string representations of the entities that triggered the event

feedback.context.error

Returns an error action result.

dynamic.action_result feedback.context.error(msg)

Parameters:

Parameter Description
msg string

The error message

feedback.context.noop

Returns a no op action result with an optional message.

dynamic.action_result feedback.context.noop(msg=None)

Parameters:

Parameter Description
msg string or NoneType

The no op message

feedback.context.record_effect

Records an effect of the current action.

feedback.context.record_effect(summary, origin_refs, destination_ref, errors=[], type="UPDATED")

Parameters:

Parameter Description
summary string

The summary of this effect
origin_refs sequence of origin_ref

The origin refs
destination_ref destination_ref

The destination ref
errors sequence of string

An optional list of errors
type string

The type of migration effect:

  • 'CREATED': A new review or change was created.
  • 'UPDATED': An existing review or change was updated.
  • 'NOOP': The change was a noop.
  • 'NOOP_AGAINST_PENDING_CHANGE': The change was a noop, relativeto an existing pending change.
  • 'INSUFFICIENT_APPROVALS': The effect couldn't happen because the change doesn't have enough approvals.
  • 'ERROR': A user attributable error happened that prevented the destination from creating/updating the change.
  • 'STARTED': The initial effect of a migration that depends on a previous one. This allows to have 'dependant' migrations defined by users.
    An example of this: a workflow migrates code from a Gerrit review to a GitHub PR, and a feedback migration migrates the test results from a CI in GitHub back to the Gerrit change.
    This effect would be created on the former one.

feedback.context.success

Returns a successful action result.

dynamic.action_result feedback.context.success()

feedback.finish_hook_context

Gives access to the feedback migration information and utilities. This context is a concrete implementation for 'after_migration' hooks.

Fields:

Name Description
action_name string

The name of the current action.
cli_labels dict[string, string]

Access labels that a user passes through flag '--labels'. For example: --labels=foo:value1,bar:value2. Then it can access in this way:cli_labels['foo'].
console Console

Get an instance of the console to report errors or warnings
destination endpoint

An object representing the destination. Can be used to query or modify the destination state
effects list of destination_effect

The list of effects that happened in the destination
origin endpoint

An object representing the origin. Can be used to query about the ref or modifying the origin state
params dict

Parameters for the function if created with core.action
revision feedback.revision_context

Get the requested/resolved revision

feedback.finish_hook_context.error

Returns an error action result.

dynamic.action_result feedback.finish_hook_context.error(msg)

Parameters:

Parameter Description
msg string

The error message

feedback.finish_hook_context.noop

Returns a no op action result with an optional message.

dynamic.action_result feedback.finish_hook_context.noop(msg=None)

Parameters:

Parameter Description
msg string or NoneType

The no op message

feedback.finish_hook_context.record_effect

Records an effect of the current action.

feedback.finish_hook_context.record_effect(summary, origin_refs, destination_ref, errors=[], type="UPDATED")

Parameters:

Parameter Description
summary string

The summary of this effect
origin_refs sequence of origin_ref

The origin refs
destination_ref destination_ref

The destination ref
errors sequence of string

An optional list of errors
type string

The type of migration effect:

  • 'CREATED': A new review or change was created.
  • 'UPDATED': An existing review or change was updated.
  • 'NOOP': The change was a noop.
  • 'NOOP_AGAINST_PENDING_CHANGE': The change was a noop, relativeto an existing pending change.
  • 'INSUFFICIENT_APPROVALS': The effect couldn't happen because the change doesn't have enough approvals.
  • 'ERROR': A user attributable error happened that prevented the destination from creating/updating the change.
  • 'STARTED': The initial effect of a migration that depends on a previous one. This allows to have 'dependant' migrations defined by users.
    An example of this: a workflow migrates code from a Gerrit review to a GitHub PR, and a feedback migration migrates the test results from a CI in GitHub back to the Gerrit change.
    This effect would be created on the former one.

feedback.finish_hook_context.success

Returns a successful action result.

dynamic.action_result feedback.finish_hook_context.success()

feedback.revision_context

Information about the revision request/resolved for the migration

Fields:

Name Description
labels dict[string, list of string]

A dictionary with the labels detected for the requested/resolved revision.

feedback.revision_context.fill_template

Replaces variables in templates with the values from this revision.

string feedback.revision_context.fill_template(template)

Parameters:

Parameter Description
template string

The template to use

Example:

Use the SHA1 in a string:

Create a custom transformation which is successful.

filled_template = revision.fill_template('Current Revision: ${GIT_SHORT_SHA1}')

filled_template will contain (for example) 'Current Revision: abcdef12'

filter_replace

A core.filter_replace transformation

Returned By:

float

The type of floating-point numbers in Starlark.

Returned By:

Consumed By:

folder

Module for dealing with local filesystem folders

folder.destination

A folder destination is a destination that puts the output in a folder. It can be used both for testing or real production migrations.Given that folder destination does not support a lot of the features of real VCS, there are some limitations on how to use it:

  • It requires passing a ref as an argument, as there is no way of calculating previous migrated changes. Alternatively, --last-rev can be used, which could migrate N changes.
  • Most likely, the workflow should use 'SQUASH' mode, as history is not supported.
  • If 'ITERATIVE' mode is used, a new temp directory will be created for each change migrated.

destination folder.destination()

Command line flags:

Name Type Description
--folder-dir string Local directory to write the output of the migration to. If the directory exists, all files will be deleted. By default Copybara will generate a temporary directory, so you shouldn't need this.

folder.origin

A folder origin is a origin that uses a folder as input. The folder is specified via the source_ref argument.

origin folder.origin(materialize_outside_symlinks=False)

Parameters:

Parameter Description
materialize_outside_symlinks bool

By default folder.origin will refuse any symlink in the migration folder that is an absolute symlink or that refers to a file outside of the folder. If this flag is set, it will materialize those symlinks as regular files in the checkout directory.

Command line flags:

Name Type Description
--folder-origin-author string Deprecated. Please use '--force-author'. Author of the change being migrated from folder.origin()
--folder-origin-ignore-invalid-symlinks boolean If an invalid symlink is found, ignore it instead of failing
--folder-origin-message string Deprecated. Please use '--force-message'. Message of the change being migrated from folder.origin()
--folder-origin-version string The version string associated with the change migrated from folder.origin(). If not specified, the default will be the folder path.

format

Module for formatting the code to Google's style/guidelines

format.buildifier

Formats the BUILD files using buildifier.

transformation format.buildifier(paths=glob([".bzl", "/BUILD", "BUILD"]), type='auto', lint="OFF", lint_warnings=[])

Parameters:

Parameter Description
paths glob or list of string or NoneType

Paths of the files to format relative to the workdir.
type string or NoneType

The type of the files. Can be 'auto', 'bzl', 'build' or 'workspace'. Note that this is not recommended to be set and might break in the future. The default is 'auto'. This mode formats as BUILD files "BUILD", "BUILD.bazel", "WORKSPACE" and "WORKSPACE.bazel" files. The rest as bzl files. Prefer to use those names for BUILD files instead of setting this flag.
lint string or NoneType

If buildifier --lint should be used. This fixes several common issues. Note that this transformation is difficult to revert. For example if it removes a load statement because is not used after removing a rule, then the reverse workflow needs to add back the load statement (core.replace or similar). Possible values: OFF, FIX. Default is OFF
lint_warnings sequence of string

Warnings used in the lint mode. Default is buildifier default

Examples:

Default usage:

The default parameters formats all BUILD and bzl files in the checkout directory:

format.buildifier()
Enable lint:

Enable lint for buildifier

format.buildifier(lint = "FIX")
Using globs:

Globs can be used to match only certain files:

format.buildifier(
    paths = glob(["foo/BUILD", "foo/**/BUILD"], exclude = ["foo/bar/BUILD"])
)

Formats all the BUILD files inside foo except for foo/bar/BUILD

Command line flags:

Name Type Description
--buildifier-batch-size int Process files in batches this size

function

The type of functions declared in Starlark.

gerrit_api_obj

Gerrit API endpoint implementation for feedback migrations and after migration hooks.

Fields:

Name Description
url string

Return the URL of this endpoint.

gerrit_api_obj.abandon_change

Abandon a Gerrit change.

gerritapi.ChangeInfo gerrit_api_obj.abandon_change(change_id)

Parameters:

Parameter Description
change_id string

The Gerrit change id.

gerrit_api_obj.delete_vote

Delete a label vote from an account owner on a Gerrit change.

gerrit_api_obj.delete_vote(change_id, account_id, label_id)

Parameters:

Parameter Description
change_id string

The Gerrit change id.
account_id string

The account owner who votes on label_id. Use 'me' or 'self' if the account owner makes this api call
label_id string

The name of the label.

gerrit_api_obj.get_actions

Retrieve the actions of a Gerrit change.

dict[string, gerritapi.getActionInfo] gerrit_api_obj.get_actions(id, revision)

Parameters:

Parameter Description
id string

The change id or change number.
revision string

The revision of the change.

gerrit_api_obj.get_change

Retrieve a Gerrit change.

gerritapi.ChangeInfo gerrit_api_obj.get_change(id, include_results=['LABELS'])

Parameters:

Parameter Description
id string

The change id or change number.
include_results sequence of string

What to include in the response. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#query-options

gerrit_api_obj.list_changes

Get changes from Gerrit based on a query. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes.

list of gerritapi.ChangeInfo gerrit_api_obj.list_changes(query, include_results=[])

Parameters:

Parameter Description
query string

The query string to list changes by. See https://gerrit-review.googlesource.com/Documentation/user-search.html#_basic_change_search.
include_results sequence of string

What to include in the response. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#query-options

gerrit_api_obj.new_destination_ref

Creates a new destination reference out of this endpoint.

destination_ref gerrit_api_obj.new_destination_ref(ref, type, url=None)

Parameters:

Parameter Description
ref string

The reference.
type string

The type of this reference.
url string or NoneType

The url associated with this reference, if any.

gerrit_api_obj.new_origin_ref

Creates a new origin reference out of this endpoint.

origin_ref gerrit_api_obj.new_origin_ref(ref)

Parameters:

Parameter Description
ref string

The reference.

gerrit_api_obj.post_review

Post a review to a Gerrit change for a particular revision. The review will be authored by the user running the tool, or the role account if running in the service.

gerritapi.ReviewResult gerrit_api_obj.post_review(change_id, revision_id, review_input)

Parameters:

Parameter Description
change_id string

The Gerrit change id.
revision_id string

The revision for which the comment will be posted.
review_input SetReviewInput

The review to post to Gerrit.

gerrit_api_obj.submit_change

Submit a Gerrit change

gerritapi.ChangeInfo gerrit_api_obj.submit_change(change_id)

Parameters:

Parameter Description
change_id string

The Gerrit change id.

gerritapi.AccountInfo

Gerrit account information.

Fields:

Name Description
account_id string

The numeric ID of the account.
email string

The email address the user prefers to be contacted through.
Only set if detailed account information is requested.
See option DETAILED_ACCOUNTS for change queries
and options DETAILS and ALL_EMAILS for account queries.
name string

The full name of the user.
Only set if detailed account information is requested.
See option DETAILED_ACCOUNTS for change queries
and option DETAILS for account queries.
secondary_emails list of string

A list of the secondary email addresses of the user.
Only set for account queries when the ALL_EMAILS option or the suggest parameter is set.
Secondary emails are only included if the calling user has the Modify Account, and hence is allowed to see secondary emails of other users.
username string

The username of the user.
Only set if detailed account information is requested.
See option DETAILED_ACCOUNTS for change queries
and option DETAILS for account queries.

gerritapi.ApprovalInfo

Gerrit approval information.

Fields:

Name Description
account_id string

The numeric ID of the account.
date string

The time and date describing when the approval was made.
email string

The email address the user prefers to be contacted through.
Only set if detailed account information is requested.
See option DETAILED_ACCOUNTS for change queries
and options DETAILS and ALL_EMAILS for account queries.
name string

The full name of the user.
Only set if detailed account information is requested.
See option DETAILED_ACCOUNTS for change queries
and option DETAILS for account queries.
secondary_emails list of string

A list of the secondary email addresses of the user.
Only set for account queries when the ALL_EMAILS option or the suggest parameter is set.
Secondary emails are only included if the calling user has the Modify Account, and hence is allowed to see secondary emails of other users.
username string

The username of the user.
Only set if detailed account information is requested.
See option DETAILED_ACCOUNTS for change queries
and option DETAILS for account queries.
value int

The vote that the user has given for the label. If present and zero, the user is permitted to vote on the label. If absent, the user is not permitted to vote on that label.

gerritapi.ChangeInfo

Gerrit change information.

Fields:

Name Description
branch string

The name of the target branch.
The refs/heads/ prefix is omitted.
change_id string

The Change-Id of the change.
created string

The timestamp of when the change was created.
current_revision string

The commit ID of the current patch set of this change.
Only set if the current revision is requested or if all revisions are requested.
id string

The ID of the change in the format "<project>~<branch>~<Change-Id>", where 'project', 'branch' and 'Change-Id' are URL encoded. For 'branch' the refs/heads/ prefix is omitted.
labels dict[string, gerritapi.LabelInfo]

The labels of the change as a map that maps the label names to LabelInfo entries.
Only set if labels or detailed labels are requested.
messages list of gerritapi.ChangeMessageInfo

Messages associated with the change as a list of ChangeMessageInfo entities.
Only set if messages are requested.
number string

The legacy numeric ID of the change.
owner gerritapi.AccountInfo

The owner of the change as an AccountInfo entity.
project string

The name of the project.
revisions dict[string, gerritapi.RevisionInfo]

All patch sets of this change as a map that maps the commit ID of the patch set to a RevisionInfo entity.
Only set if the current revision is requested (in which case it will only contain a key for the current revision) or if all revisions are requested.
status string

The status of the change (NEW, MERGED, ABANDONED).
subject string

The subject of the change (header line of the commit message).
submit_requirements list of SubmitRequirementResultInfo

A list of the evaluated submit requirements for the change.
submittable bool

Whether the change has been approved by the project submit rules. Only set if requested via additional field SUBMITTABLE.
submitted string

The timestamp of when the change was submitted.
topic string

The topic to which this change belongs.
triplet_id string

The ID of the change in the format "''", where 'project' and 'branch' are URL encoded. For 'branch' the refs/heads/ prefix is omitted.
updated string

The timestamp of when the change was last updated.
work_in_progress bool

Whether the change is marked as "Work in progress".

Returned By:

gerritapi.ChangeMessageInfo

Gerrit change message information.

Fields:

Name Description
author gerritapi.AccountInfo

Author of the message as an AccountInfo entity.
Unset if written by the Gerrit system.
date string

The timestamp of when this identity was constructed.
id string

The ID of the message.
message string

The text left by the user.
real_author gerritapi.AccountInfo

Real author of the message as an AccountInfo entity.
Set if the message was posted on behalf of another user.
revision_number int

Which patchset (if any) generated this message.
tag string

Value of the tag field from ReviewInput set while posting the review. NOTE: To apply different tags on on different votes/comments multiple invocations of the REST call are required.

gerritapi.ChangesQuery

Input for listing Gerrit changes. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#list-changes

gerritapi.CommitInfo

Gerrit commit information.

Fields:

Name Description
author gerritapi.GitPersonInfo

The author of the commit as a GitPersonInfo entity.
commit string

The commit ID. Not set if included in a RevisionInfo entity that is contained in a map which has the commit ID as key.
committer gerritapi.GitPersonInfo

The committer of the commit as a GitPersonInfo entity.
message string

The commit message.
parents list of gerritapi.ParentCommitInfo

The parent commits of this commit as a list of CommitInfo entities. In each parent only the commit and subject fields are populated.
subject string

The subject of the commit (header line of the commit message).

gerritapi.getActionInfo

Gerrit actions information.

Fields:

Name Description
enabled bool

If true the action is permitted at this time and the caller is likely allowed to execute it.
label string

Short title to display to a user describing the action

Returned By:

gerritapi.GitPersonInfo

Git person information.

Fields:

Name Description
date string

The timestamp of when this identity was constructed.
email string

The email address of the author/committer.
name string

The name of the author/committer.

gerritapi.LabelInfo

Gerrit label information.

Fields:

Name Description
all list of gerritapi.ApprovalInfo

List of all approvals for this label as a list of ApprovalInfo entities. Items in this list may not represent actual votes cast by users; if a user votes on any label, a corresponding ApprovalInfo will appear in this list for all labels.
approved gerritapi.AccountInfo

One user who approved this label on the change (voted the maximum value) as an AccountInfo entity.
blocking bool

If true, the label blocks submit operation. If not set, the default is false.
default_value int

The default voting value for the label. This value may be outside the range specified in permitted_labels.
disliked gerritapi.AccountInfo

One user who disliked this label on the change (voted negatively, but not the minimum value) as an AccountInfo entity.
recommended gerritapi.AccountInfo

One user who recommended this label on the change (voted positively, but not the maximum value) as an AccountInfo entity.
rejected gerritapi.AccountInfo

One user who rejected this label on the change (voted the minimum value) as an AccountInfo entity.
value int

The voting value of the user who recommended/disliked this label on the change if it is not "+1"/"-1".
values dict[string, string]

A map of all values that are allowed for this label. The map maps the values ("-2", "-1", "0", "+1", "+2") to the value descriptions.

gerritapi.ParentCommitInfo

Gerrit parent commit information.

Fields:

Name Description
commit string

The commit ID. Not set if included in a RevisionInfo entity that is contained in a map which has the commit ID as key.
subject string

The subject of the commit (header line of the commit message).

gerritapi.ReviewResult

Gerrit review result.

Fields:

Name Description
labels dict[string, int]

Map of labels to values after the review was posted.
ready bool

If true, the change was moved from WIP to ready for review as a result of this action. Not set if false.

Returned By:

gerritapi.RevisionInfo

Gerrit revision information.

Fields:

Name Description
commit gerritapi.CommitInfo

The commit of the patch set as CommitInfo entity.
created string

The timestamp of when the patch set was created.
kind string

The change kind. Valid values are REWORK, TRIVIAL_REBASE, MERGE_FIRST_PARENT_UPDATE, NO_CODE_CHANGE, and NO_CHANGE.
patchset_number int

The patch set number, or edit if the patch set is an edit.
ref string

The Git reference for the patch set.
uploader gerritapi.AccountInfo

The uploader of the patch set as an AccountInfo entity.

gerritapi.SubmitRequirementExpressionInfo

Result of evaluating submit requirement expression

Fields:

Name Description
expression string

The submit requirement expression as a string.
fulfilled bool

If true, this submit requirement result was created from a legacy SubmitRecord. Otherwise, it was created by evaluating a submit requirement.
status string

The status of the submit requirement evaluation.

git

Set of functions to define Git origins and destinations.

Command line flags:

Name Type Description
--allowed-git-push-options list This is a flag used to allowlist push options sent to git servers. E.g. copybara copy.bara.sky --git-push-option="foo,bar" would make copybara validate push so that the only push options (if there are any) used are 'foo' and 'bar'. If this flag is unset, it will skip push options validation. Set to "" to allow no push options.
--experiment-checkout-affected-files boolean If set, copybara will only checkout affected files at git origin. Note that this is experimental.
--git-credential-helper-store-file string Credentials store file to be used. See https://git-scm.com/docs/git-credential-store
--git-no-verify boolean Pass the '--no-verify' option to git pushes and commits to disable git commit hooks.
--git-origin-fetch-depth integer Use a shallow clone of the specified depth for git.origin. If set, only the n most recent changes' tree states are imported with older changes omitted.
--git-push-option list This is a repeatable flag used to set git push level flags to send to git servers. E.g. copybara copy.bara.sky --git-push-option foo --git-push-option bar would make git operations done by copybara under the hood use the --push-option flags: git push -push-option=foo -push-option=bar ...
--git-tag-overwrite boolean If set, copybara will force update existing git tag
--nogit-credential-helper-store boolean Disable using credentials store. See https://git-scm.com/docs/git-credential-store
--nogit-prompt boolean Disable username/password prompt and fail if no credentials are found. This flag sets the environment variable GIT_TERMINAL_PROMPT which is intended for automated jobs running Git https://git-scm.com/docs/git/2.3.0#git-emGITTERMINALPROMPTem

git.destination

Creates a commit in a git repository using the transformed worktree.

For GitHub use git.github_destination. For creating Pull Requests in GitHub, use git.github_pr_destination. For creating a Gerrit change use git.gerrit_destination.

Given that Copybara doesn't ask for user/password in the console when doing the push to remote repos, you have to use ssh protocol, have the credentials cached or use a credential manager.

destination git.destination(url, push='master', tag_name=None, tag_msg=None, fetch=None, partial_fetch=False, integrates=None, primary_branch_migration=False, checker=None, credentials=None)

Parameters:

Parameter Description
url string

Indicates the URL to push to as well as the URL from which to get the parent commit
push string

Reference to use for pushing the change, for example 'main'.
tag_name string or NoneType

A template string that refers to a tag name. If tag_name exists, overwrite this tag only if flag git-tag-overwrite is set. Note that tag creation is best-effort and migration will succeed even if the tag cannot be created. Usage: Users can use a string or a string with a label. For instance ${label}_tag_name. And the value of label must be in changes' label list. Otherwise, tag won't be created.
tag_msg string or NoneType

A template string that refers to the commit msg of a tag. If set, we will create an annotated tag when tag_name is set. Usage: Users can use a string or a string with a label. For instance ${label}_message. And the value of label must be in changes' label list. Otherwise, tag will be created with sha1's commit msg.
fetch string or NoneType

Indicates the ref from which to get the parent commit. Defaults to push value if None
partial_fetch bool

This is an experimental feature that only works for certain origin globs.
integrates sequence of git_integrate or NoneType

Integrate changes from a url present in the migrated change label. Defaults to a semi-fake merge if COPYBARA_INTEGRATE_REVIEW label is present in the message
primary_branch_migration bool

When enabled, copybara will ignore the 'push' and 'fetch' params if either is 'master' or 'main' and instead try to establish the default git branch. If this fails, it will fall back to the param's declared value.
This is intended to help migrating to the new standard of using 'main' without breaking users relying on the legacy default.
checker checker or NoneType

A checker that can check leaks or other checks in the commit created.

credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--git-committer-email string If set, overrides the committer e-mail for the generated commits in git destination.
--git-committer-name string If set, overrides the committer name for the generated commits in git destination.
--git-destination-fetch string If set, overrides the git destination fetch reference.
--git-destination-fetch-depth integer Use a shallow clone of the specified depth for git.destination
--git-destination-ignore-integration-errors boolean If an integration error occurs, ignore it and continue without the integrate
--git-destination-last-rev-first-parent boolean Use git --first-parent flag when looking for last-rev in previous commits
--git-destination-non-fast-forward boolean Allow non-fast-forward pushes to the destination. We only allow this when used with different push != fetch references.
--git-destination-path string If set, the tool will use this directory for the local repository. Note that if the directory exists it needs to be a git repository. Copybara will revert any staged/unstaged changes. For example, you can override destination url with a local non-bare repo (or existing empty folder) with this flag.
--git-destination-push string If set, overrides the git destination push reference.
--git-destination-url string If set, overrides the git destination URL.
--git-skip-checker boolean If true and git.destination has a configured checker, it will not be used in the migration.
--nogit-destination-rebase boolean Don't rebase the change automatically for workflows CHANGE_REQUEST mode

git.gerrit_api

Defines a feedback API endpoint for Gerrit, that exposes relevant Gerrit API operations.

endpoint_provider git.gerrit_api(url, checker=None, allow_submit=False)

Parameters:

Parameter Description
url string

Indicates the Gerrit repo URL.
checker checker or NoneType

A checker for the Gerrit API transport.
allow_submit bool

Enable the submit_change method

Command line flags:

Name Type Description
--force-gerrit-submit boolean Override the gerrit submit setting that is set in the config. This also flips the submit bit.
--gerrit-change-id string ChangeId to use in the generated commit message. Use this flag if you want to reuse the same Gerrit review for an export.
--gerrit-new-change boolean Create a new change instead of trying to reuse an existing one.
--gerrit-topic string Gerrit topic to use

git.gerrit_destination

Creates a change in Gerrit using the transformed worktree. If this is used in iterative mode, then each commit pushed in a single Copybara invocation will have the correct commit parent. The reviews generated can then be easily done in the correct order without rebasing.

destination git.gerrit_destination(url, fetch, push_to_refs_for=fetch value, submit=False, partial_fetch=False, notify=None, change_id_policy='FAIL_IF_PRESENT', allow_empty_diff_patchset=True, reviewers=[], cc=[], labels=[], api_checker=None, integrates=None, topic=None, gerrit_submit=False, primary_branch_migration=False, checker=None, credentials=None)

Parameters:

Parameter Description
url string

Indicates the URL to push to as well as the URL from which to get the parent commit
fetch string

Indicates the ref from which to get the parent commit
push_to_refs_for string or NoneType

Review branch to push the change to, for example setting this to 'feature_x' causes the destination to push to 'refs/for/feature_x'. It defaults to 'fetch' value.
submit bool

If true, skip the push thru Gerrit refs/for/branch and directly push to branch. This is effectively a git.destination that sets a Change-Id
partial_fetch bool

This is an experimental feature that only works for certain origin globs.
notify string or NoneType

Type of Gerrit notify option (https://gerrit-review.googlesource.com/Documentation/user-upload.html#notify). Sends notifications by default.
change_id_policy string

What to do in the presence or absent of Change-Id in message:

  • 'REQUIRE': Require that the change_id is present in the message as a valid label
  • 'FAIL_IF_PRESENT': Fail if found in message
  • 'REUSE': Reuse if present. Otherwise generate a new one
  • 'REPLACE': Replace with a new one if found
allow_empty_diff_patchset bool

By default Copybara will upload a new PatchSet to Gerrit without checking the previous one. If this set to false, Copybara will download current PatchSet and check the diff against the new diff.
reviewers sequence

The list of the reviewers to add. Each element in the list is: an email (e.g. "foo@example.com" or label (e.g. "${SOME_GERRIT_REVIEWER}). These assume that users have already registered on the Gerrit host and has access to the repos.
cc sequence

The list of the email addresses or users that will be CCed in the review. Can use labels as the reviewers field.
labels sequence

The list of labels to be pushed with the change. The format is the label along with the associated value. For example: Run-Presubmit+1
api_checker checker or NoneType

A checker for the Gerrit API endpoint provided for after_migration hooks. This field is not required if the workflow hooks don't use the origin/destination endpoints.
integrates sequence of git_integrate or NoneType

Integrate changes from a url present in the migrated change label. Defaults to a semi-fake merge if COPYBARA_INTEGRATE_REVIEW label is present in the message
topic string or NoneType

Sets the topic of the Gerrit change created.

By default it sets no topic. This field accepts a template with labels. For example: "topic_${CONTEXT_REFERENCE}"
gerrit_submit bool

By default, Copybara uses git commit/push to the main branch when submit = True. If this flag is enabled, it will update the Gerrit change with the latest commit and submit using Gerrit.
primary_branch_migration bool

When enabled, copybara will ignore the 'push_to_refs_for' and 'fetch' params if either is 'master' or 'main' and instead try to establish the default git branch. If this fails, it will fall back to the param's declared value.
This is intended to help migrating to the new standard of using 'main' without breaking users relying on the legacy default.
checker checker or NoneType

A checker that validates the commit files & message. If api_checker is not set, it will also be used for checking API calls. If only api_checkeris used, that checker will only apply to API calls.
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--force-gerrit-submit boolean Override the gerrit submit setting that is set in the config. This also flips the submit bit.
--gerrit-change-id string ChangeId to use in the generated commit message. Use this flag if you want to reuse the same Gerrit review for an export.
--gerrit-new-change boolean Create a new change instead of trying to reuse an existing one.
--gerrit-topic string Gerrit topic to use
--git-committer-email string If set, overrides the committer e-mail for the generated commits in git destination.
--git-committer-name string If set, overrides the committer name for the generated commits in git destination.
--git-destination-fetch string If set, overrides the git destination fetch reference.
--git-destination-fetch-depth integer Use a shallow clone of the specified depth for git.destination
--git-destination-ignore-integration-errors boolean If an integration error occurs, ignore it and continue without the integrate
--git-destination-last-rev-first-parent boolean Use git --first-parent flag when looking for last-rev in previous commits
--git-destination-non-fast-forward boolean Allow non-fast-forward pushes to the destination. We only allow this when used with different push != fetch references.
--git-destination-path string If set, the tool will use this directory for the local repository. Note that if the directory exists it needs to be a git repository. Copybara will revert any staged/unstaged changes. For example, you can override destination url with a local non-bare repo (or existing empty folder) with this flag.
--git-destination-push string If set, overrides the git destination push reference.
--git-destination-url string If set, overrides the git destination URL.
--git-skip-checker boolean If true and git.destination has a configured checker, it will not be used in the migration.
--nogit-destination-rebase boolean Don't rebase the change automatically for workflows CHANGE_REQUEST mode

git.gerrit_origin

Defines a Git origin for Gerrit reviews.

Implicit labels that can be used/exposed:

  • GERRIT_CHANGE_NUMBER: The change number for the Gerrit review.
  • GERRIT_CHANGE_ID: The change id for the Gerrit review.
  • GERRIT_CHANGE_DESCRIPTION: The description of the Gerrit review.
  • COPYBARA_INTEGRATE_REVIEW: A label that when exposed, can be used to integrate automatically in the reverse workflow.
  • GERRIT_CHANGE_BRANCH: The destination branch for thechange
  • GERRIT_CHANGE_TOPIC: The change topic
  • GERRIT_COMPLETE_CHANGE_ID: Complete Change-Id with project, branch and Change-Id
  • GERRIT_OWNER_EMAIL: Owner email
  • GERRIT_REVIEWER_EMAIL: Multiple value field with the email of the reviewers
  • GERRIT_CC_EMAIL: Multiple value field with the email of the people/groups in cc

origin git.gerrit_origin(url, ref=None, submodules='NO', excluded_submodules=[], first_parent=True, partial_fetch=False, api_checker=None, patch=None, branch=None, describe_version=None, ignore_gerrit_noop=False, primary_branch_migration=False, import_wip_changes=True)

Parameters:

Parameter Description
url string

Indicates the URL of the git repository
ref string or NoneType

DEPRECATED. Use git.origin for submitted branches.
submodules string

Download submodules. Valid values: NO, YES, RECURSIVE.
excluded_submodules sequence of string

A list of names (not paths, e.g. "foo" is the submodule name if [submodule "foo"] appears in the .gitmodules file) of submodules that will not be download even if 'submodules' is set to YES or RECURSIVE.

first_parent bool

If true, it only uses the first parent when looking for changes. Note that when disabled in ITERATIVE mode, it will try to do a migration for each change of the merged branch.
partial_fetch bool

If true, partially fetch git repository by only fetching affected files.
api_checker checker or NoneType

A checker for the Gerrit API endpoint provided for after_migration hooks. This field is not required if the workflow hooks don't use the origin/destination endpoints.
patch transformation or NoneType

Patch the checkout dir. The difference with patch.apply transformation is that here we can apply it using three-way
branch string or NoneType

Limit the import to changes that are for this branch. By default imports everything.
describe_version bool or NoneType

Download tags and use 'git describe' to create four labels with a meaningful version identifier:

- GIT_DESCRIBE_CHANGE_VERSION: The version for the change or changes being migrated. The value changes per change in ITERATIVE mode and will be the latest migrated change in SQUASH (In other words, doesn't include excluded changes). this is normally what users want to use.
- GIT_DESCRIBE_REQUESTED_VERSION: git describe for the requested/head version. Constant in ITERATIVE mode and includes filtered changes.
-GIT_DESCRIBE_FIRST_PARENT: git describe for the first parent version.
-GIT_SEQUENTIAL_REVISION_NUMBER: The sequential number of the commit. Falls back to the SHA1 if not applicable.
ignore_gerrit_noop bool

Option to not migrate Gerrit changes that do not change origin_files
primary_branch_migration bool

When enabled, copybara will ignore the 'ref' param if it is 'master' or 'main' and instead try to establish the default git branch. If this fails, it will fall back to the 'ref' param.
This is intended to help migrating to the new standard of using 'main' without breaking users relying on the legacy default.
import_wip_changes bool

When set to true, Copybara will migrate changes marked as Work in Progress (WIP).

Command line flags:

Name Type Description
--force-gerrit-submit boolean Override the gerrit submit setting that is set in the config. This also flips the submit bit.
--gerrit-change-id string ChangeId to use in the generated commit message. Use this flag if you want to reuse the same Gerrit review for an export.
--gerrit-new-change boolean Create a new change instead of trying to reuse an existing one.
--gerrit-topic string Gerrit topic to use
--git-fuzzy-last-rev boolean By default Copybara will try to migrate the revision listed as the version in the metadata file from github. This flag tells Copybara to first find the git tag which most closely matches the metadata version, and use that for the migration.
--git-origin-log-batch int Read the origin git log in batches of n commits. Might be needed for large migrations resulting in git logs of more than 1 GB.
--git-origin-non-linear-history boolean Read the full git log and skip changes before the from ref rather than using a log path.
--git-origin-rebase-ref string When importing a change from a Git origin ref, it will be rebased to this ref, if set. A common use case: importing a Github PR, rebase it to the main branch (usually 'master'). Note that, if the repo uses submodules, they won't be rebased.
--nogit-origin-version-selector boolean Disable the version selector for the migration. Only useful for forcing a migration to the passed version in the CLI

git.gerrit_trigger

Defines a feedback trigger based on updates on a Gerrit change.

trigger git.gerrit_trigger(url, checker=None, events=[], allow_submit=False)

Parameters:

Parameter Description
url string

Indicates the Gerrit repo URL.
checker checker or NoneType

A checker for the Gerrit API transport provided by this trigger.
events sequence of string or dict of sequence or NoneType

Types of events to monitor. Optional. Can either be a list of event types or a dict of event types to particular events of that type, e.g. ['LABELS'] or {'LABELS': 'my_label_name'}.
Valid values for event types are: 'LABELS', 'SUBMIT_REQUIREMENTS'
allow_submit bool

Enable the submit_change method in the endpoint provided

Command line flags:

Name Type Description
--force-gerrit-submit boolean Override the gerrit submit setting that is set in the config. This also flips the submit bit.
--gerrit-change-id string ChangeId to use in the generated commit message. Use this flag if you want to reuse the same Gerrit review for an export.
--gerrit-new-change boolean Create a new change instead of trying to reuse an existing one.
--gerrit-topic string Gerrit topic to use

git.github_api

Defines a feedback API endpoint for GitHub, that exposes relevant GitHub API operations.

endpoint_provider git.github_api(url, checker=None, credentials=None)

Parameters:

Parameter Description
url string

Indicates the GitHub repo URL.
checker checker or NoneType

A checker for the GitHub API transport.
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--allstar-app-ids list Flag used to set AllStar GitHub app id aliases. See https://github.com/ossf/allstar.
--github-api-bearer-auth boolean If using a token for GitHub access, bearer auth might be required
--github-destination-delete-pr-branch boolean Overwrite git.github_destination delete_pr_branch field
--gql-commit-history-override list Flag used to target GraphQL params 'first' arguments in the event the defaults are over or underusing the api ratelimit. The flag value should be semicolon separated. This should be rarely used for repos that don't fit well in our defaults. E.g. '50;5;5' represent 50 commits, 5 PRs for each commit, 5 reviews per PR

git.github_destination

Creates a commit in a GitHub repository branch (for example master). For creating PullRequest use git.github_pr_destination.

destination git.github_destination(url, push='master', fetch=None, pr_branch_to_update=None, partial_fetch=False, delete_pr_branch=False, integrates=None, api_checker=None, primary_branch_migration=False, tag_name=None, tag_msg=None, checker=None, credentials=None, push_to_fork=False)

Parameters:

Parameter Description
url string

Indicates the URL to push to as well as the URL from which to get the parent commit
push string

Reference to use for pushing the change, for example 'main'.
fetch string or NoneType

Indicates the ref from which to get the parent commit. Defaults to push value if None
pr_branch_to_update string or NoneType

A template string that refers to a pull request branch in the same repository will be updated to current commit of this push branch only if pr_branch_to_update exists. The reason behind this field is that presubmiting changes creates and leaves a pull request open. By using this, we can automerge/close this type of pull requests. As a result, users will see this pr_branch_to_update as merged to this push branch. Usage: Users can use a string or a string with a label. For instance ${label}_pr_branch_name. And the value of label must be in changes' label list. Otherwise, nothing will happen.
partial_fetch bool

This is an experimental feature that only works for certain origin globs.
delete_pr_branch bool or NoneType

When pr_branch_to_update is enabled, it will delete the branch reference after the push to the branch and main branch (i.e master) happens. This allows to cleanup temporary branches created for testing.
integrates sequence of git_integrate or NoneType

Integrate changes from a url present in the migrated change label. Defaults to a semi-fake merge if COPYBARA_INTEGRATE_REVIEW label is present in the message
api_checker checker or NoneType

A checker for the Gerrit API endpoint provided for after_migration hooks. This field is not required if the workflow hooks don't use the origin/destination endpoints.
primary_branch_migration bool

When enabled, copybara will ignore the 'push' and 'fetch' params if either is 'master' or 'main' and instead try to establish the default git branch. If this fails, it will fall back to the param's declared value.
This is intended to help migrating to the new standard of using 'main' without breaking users relying on the legacy default.
tag_name string or NoneType

A template string that specifies to a tag name. If the tag already exists, copybara will only overwrite it if the --git-tag-overwrite flag is set.
Note that tag creation is best-effort and the migration will succeed even if the tag cannot be created. Usage: Users can use a string or a string with a label. For instance ${label}_tag_name. And the value of label must be in changes' label list. Otherwise, tag won't be created.
tag_msg string or NoneType

A template string that refers to the commit msg for a tag. If set, copybara willcreate an annotated tag with this custom message
Usage: Labels in the string will be resolved. E.g. .${label}_message.By default, the tag will be created with the labeled commit's message.
checker checker or NoneType

A checker that validates the commit files & message. If api_checker is not set, it will also be used for checking API calls. If only api_checkeris used, that checker will only apply to API calls.
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--allstar-app-ids list Flag used to set AllStar GitHub app id aliases. See https://github.com/ossf/allstar.
--git-committer-email string If set, overrides the committer e-mail for the generated commits in git destination.
--git-committer-name string If set, overrides the committer name for the generated commits in git destination.
--git-destination-fetch string If set, overrides the git destination fetch reference.
--git-destination-fetch-depth integer Use a shallow clone of the specified depth for git.destination
--git-destination-ignore-integration-errors boolean If an integration error occurs, ignore it and continue without the integrate
--git-destination-last-rev-first-parent boolean Use git --first-parent flag when looking for last-rev in previous commits
--git-destination-non-fast-forward boolean Allow non-fast-forward pushes to the destination. We only allow this when used with different push != fetch references.
--git-destination-path string If set, the tool will use this directory for the local repository. Note that if the directory exists it needs to be a git repository. Copybara will revert any staged/unstaged changes. For example, you can override destination url with a local non-bare repo (or existing empty folder) with this flag.
--git-destination-push string If set, overrides the git destination push reference.
--git-destination-url string If set, overrides the git destination URL.
--git-skip-checker boolean If true and git.destination has a configured checker, it will not be used in the migration.
--github-api-bearer-auth boolean If using a token for GitHub access, bearer auth might be required
--github-destination-delete-pr-branch boolean Overwrite git.github_destination delete_pr_branch field
--gql-commit-history-override list Flag used to target GraphQL params 'first' arguments in the event the defaults are over or underusing the api ratelimit. The flag value should be semicolon separated. This should be rarely used for repos that don't fit well in our defaults. E.g. '50;5;5' represent 50 commits, 5 PRs for each commit, 5 reviews per PR
--nogit-destination-rebase boolean Don't rebase the change automatically for workflows CHANGE_REQUEST mode

git.github_origin

Defines a Git origin for a Github repository. This origin should be used for public branches. Use github_pr_origin for importing Pull Requests.

origin git.github_origin(url, ref=None, submodules='NO', excluded_submodules=[], first_parent=True, partial_fetch=False, patch=None, describe_version=None, version_selector=None, primary_branch_migration=False, enable_lfs=False, credentials=None)

Parameters:

Parameter Description
url string

Indicates the URL of the git repository
ref string or NoneType

Represents the default reference that will be used for reading the revision from the git repository. For example: 'master'
submodules string

Download submodules. Valid values: NO, YES, RECURSIVE.
excluded_submodules sequence of string

A list of names (not paths, e.g. "foo" is the submodule name if [submodule "foo"] appears in the .gitmodules file) of submodules that will not be download even if 'submodules' is set to YES or RECURSIVE.

first_parent bool

If true, it only uses the first parent when looking for changes. Note that when disabled in ITERATIVE mode, it will try to do a migration for each change of the merged branch.
partial_fetch bool

If true, partially fetch git repository by only fetching affected files.
patch transformation or NoneType

Patch the checkout dir. The difference with patch.apply transformation is that here we can apply it using three-way
describe_version bool or NoneType

Download tags and use 'git describe' to create four labels with a meaningful version identifier:

- GIT_DESCRIBE_CHANGE_VERSION: The version for the change or changes being migrated. The value changes per change in ITERATIVE mode and will be the latest migrated change in SQUASH (In other words, doesn't include excluded changes). this is normally what users want to use.
- GIT_DESCRIBE_REQUESTED_VERSION: git describe for the requested/head version. Constant in ITERATIVE mode and includes filtered changes.
-GIT_DESCRIBE_FIRST_PARENT: git describe for the first parent version.
-GIT_SEQUENTIAL_REVISION_NUMBER: The sequential number of the commit. Falls back to the SHA1 if not applicable.
version_selector VersionSelector or NoneType

Select a custom version (tag)to migrate instead of 'ref'. Version selector is expected to match the whole refspec (e.g. 'refs/heads/${n1}')
primary_branch_migration bool

When enabled, copybara will ignore the 'ref' param if it is 'master' or 'main' and instead try to establish the default git branch. If this fails, it will fall back to the 'ref' param.
This is intended to help migrating to the new standard of using 'main' without breaking users relying on the legacy default.
enable_lfs bool

If true, Large File Storage support is enabled for the origin.
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--allstar-app-ids list Flag used to set AllStar GitHub app id aliases. See https://github.com/ossf/allstar.
--git-fuzzy-last-rev boolean By default Copybara will try to migrate the revision listed as the version in the metadata file from github. This flag tells Copybara to first find the git tag which most closely matches the metadata version, and use that for the migration.
--git-origin-log-batch int Read the origin git log in batches of n commits. Might be needed for large migrations resulting in git logs of more than 1 GB.
--git-origin-non-linear-history boolean Read the full git log and skip changes before the from ref rather than using a log path.
--git-origin-rebase-ref string When importing a change from a Git origin ref, it will be rebased to this ref, if set. A common use case: importing a Github PR, rebase it to the main branch (usually 'master'). Note that, if the repo uses submodules, they won't be rebased.
--github-api-bearer-auth boolean If using a token for GitHub access, bearer auth might be required
--github-destination-delete-pr-branch boolean Overwrite git.github_destination delete_pr_branch field
--gql-commit-history-override list Flag used to target GraphQL params 'first' arguments in the event the defaults are over or underusing the api ratelimit. The flag value should be semicolon separated. This should be rarely used for repos that don't fit well in our defaults. E.g. '50;5;5' represent 50 commits, 5 PRs for each commit, 5 reviews per PR
--nogit-origin-version-selector boolean Disable the version selector for the migration. Only useful for forcing a migration to the passed version in the CLI

git.github_pr_destination

Creates changes in a new pull request in the destination.

destination git.github_pr_destination(url, destination_ref='master', pr_branch=None, partial_fetch=False, allow_empty_diff=True, allow_empty_diff_merge_statuses=[], allow_empty_diff_check_suites_to_conclusion={}, title=None, body=None, assignees=[], integrates=None, api_checker=None, update_description=False, primary_branch_migration=False, checker=None, draft=False, credentials=None)

Parameters:

Parameter Description
url string

Url of the GitHub project. For example "https://github.com/google/copybara'"
destination_ref string

Destination reference for the change.
pr_branch string or NoneType

Customize the pull request branch. The token ${CONTEXT_REFERENCE} will be replaced with the corresponding stable reference (head, PR number, Gerrit change number, etc.).
partial_fetch bool

This is an experimental feature that only works for certain origin globs.
allow_empty_diff bool

By default, copybara migrates changes without checking existing PRs. If set, copybara will skip pushing a change to an existing PR only if the git three of the pending migrating change is the same as the existing PR.
allow_empty_diff_merge_statuses sequence of string

EXPERIMENTAL feature. By default, if allow_empty_diff = False is set, Copybara skips uploading the change if the tree hasn't changed and it can be merged. When this list is set with values from https://docs.github.com/en/github-ae@latest/graphql/reference/enums#mergestatestatus, it will still upload for the configured statuses. For example, if a user sets it to ['DIRTY', 'UNSTABLE', 'UNKNOWN'] (the recommended set to use), it wouldn't skip upload if test failed in GitHub for previous export, or if the change cannot be merged. Note that this field is experimental and is subject to change by GitHub without notice. Please consult Copybara team before using this field.
allow_empty_diff_check_suites_to_conclusion dict of string

EXPERIMENTAL feature. By default, if allow_empty_diff = False is set, Copybara skips uploading the change if the tree hasn't changed and it can be merged.

This field allows to configure Check suit slugs and conclusions for those check suites where an upload needs to happen despite no code changes. For example this can be used to upload if tests are failing. A Very common usage would be {"github-actions" : ["none", "failure", "timed_out", "cancelled"]}: This would upload changes when Checks are in progress, has failed, timeout or being cancelled. github-actions check suit slug name is the default name for checks run by GitHub actions where the suit is not given a name.
title string or NoneType

When creating (or updating if update_description is set) a pull request, use this title. By default it uses the change first line. This field accepts a template with labels. For example: "Change ${CONTEXT_REFERENCE}"
body string or NoneType

When creating (or updating if update_description is set) a pull request, use this body. By default it uses the change summary. This field accepts a template with labels. For example: "Change ${CONTEXT_REFERENCE}"
assignees sequence of string

The assignees to set when creating a new pull request. The maximum number of assignees is 10 and the assignees must be GitHub usernames or a label that can be resolved to a GitHub username. For example: assignees = ["github-repo-owner1", "${YOUR_LABEL}"]
integrates sequence of git_integrate or NoneType

Integrate changes from a url present in the migrated change label. Defaults to a semi-fake merge if COPYBARA_INTEGRATE_REVIEW label is present in the message
api_checker checker or NoneType

A checker for the GitHub API endpoint provided for after_migration hooks. This field is not required if the workflow hooks don't use the origin/destination endpoints.
update_description bool

By default, Copybara only set the title and body of the PR when creating the PR. If this field is set to true, it will update those fields for every update.
primary_branch_migration bool

When enabled, copybara will ignore the 'desination_ref' param if it is 'master' or 'main' and instead try to establish the default git branch. If this fails, it will fall back to the param's declared value.
This is intended to help migrating to the new standard of using 'main' without breaking users relying on the legacy default.
checker checker or NoneType

A checker that validates the commit files & message. If api_checker is not set, it will also be used for checking API calls. If only api_checkeris used, that checker will only apply to API calls.
draft bool

Flag create pull request as draft or not.
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Examples:

Common usage:

Create a branch by using copybara's computerIdentity algorithm:

git.github_pr_destination(
        url = "https://github.com/google/copybara",
        destination_ref = "master",
    )
Using pr_branch with label:

Customize pr_branch with context reference:

git.github_pr_destination(
        url = "https://github.com/google/copybara",
         destination_ref = "master",
         pr_branch = 'test_${CONTEXT_REFERENCE}',
    )
Using pr_branch with constant string:

Customize pr_branch with a constant string:

git.github_pr_destination(
        url = "https://github.com/google/copybara",
        destination_ref = "master",
        pr_branch = 'test_my_branch',
    )

Command line flags:

Name Type Description
--allstar-app-ids list Flag used to set AllStar GitHub app id aliases. See https://github.com/ossf/allstar.
--git-committer-email string If set, overrides the committer e-mail for the generated commits in git destination.
--git-committer-name string If set, overrides the committer name for the generated commits in git destination.
--git-destination-fetch string If set, overrides the git destination fetch reference.
--git-destination-fetch-depth integer Use a shallow clone of the specified depth for git.destination
--git-destination-ignore-integration-errors boolean If an integration error occurs, ignore it and continue without the integrate
--git-destination-last-rev-first-parent boolean Use git --first-parent flag when looking for last-rev in previous commits
--git-destination-non-fast-forward boolean Allow non-fast-forward pushes to the destination. We only allow this when used with different push != fetch references.
--git-destination-path string If set, the tool will use this directory for the local repository. Note that if the directory exists it needs to be a git repository. Copybara will revert any staged/unstaged changes. For example, you can override destination url with a local non-bare repo (or existing empty folder) with this flag.
--git-destination-push string If set, overrides the git destination push reference.
--git-destination-url string If set, overrides the git destination URL.
--git-skip-checker boolean If true and git.destination has a configured checker, it will not be used in the migration.
--github-api-bearer-auth boolean If using a token for GitHub access, bearer auth might be required
--github-destination-delete-pr-branch boolean Overwrite git.github_destination delete_pr_branch field
--github-destination-pr-branch string If set, uses this branch for creating the pull request instead of using a generated one
--github-destination-pr-create boolean If the pull request should be created
--gql-commit-history-override list Flag used to target GraphQL params 'first' arguments in the event the defaults are over or underusing the api ratelimit. The flag value should be semicolon separated. This should be rarely used for repos that don't fit well in our defaults. E.g. '50;5;5' represent 50 commits, 5 PRs for each commit, 5 reviews per PR
--nogit-destination-rebase boolean Don't rebase the change automatically for workflows CHANGE_REQUEST mode

git.github_pr_origin

Defines a Git origin for Github pull requests.

Implicit labels that can be used/exposed:

  • GITHUB_PR_NUMBER: The pull request number if the reference passed was in the form of https://github.com/project/pull/123, refs/pull/123/head or refs/pull/123/master.
  • COPYBARA_INTEGRATE_REVIEW: A label that when exposed, can be used to integrate automatically in the reverse workflow.
  • GITHUB_BASE_BRANCH: The name of the branch which serves as the base for the Pull Request.
  • GITHUB_BASE_BRANCH_SHA1: The SHA-1 of the commit used as baseline. Generally, the baseline commit is the point of divergence between the PR's 'base' and 'head' branches. When use_merge = True is specified, the baseline is instead the tip of the PR's base branch.
  • GITHUB_PR_USE_MERGE: Equal to 'true' if the workflow is importing a GitHub PR 'merge' commit and 'false' when importing a GitHub PR 'head' commit.
  • GITHUB_PR_TITLE: Title of the Pull Request.
  • GITHUB_PR_BODY: Body of the Pull Request.
  • GITHUB_PR_URL: GitHub url of the Pull Request.
  • GITHUB_PR_HEAD_SHA: The SHA-1 of the head commit of the pull request.
  • GITHUB_PR_USER: The login of the author the pull request.
  • GITHUB_PR_ASSIGNEE: A repeated label with the login of the assigned users.
  • GITHUB_PR_REVIEWER_APPROVER: A repeated label with the login of users that have participated in the review and that can approve the import. Only populated if review_state field is set. Every reviewers type matching review_approvers will be added to this list.
  • GITHUB_PR_REVIEWER_OTHER: A repeated label with the login of users that have participated in the review but cannot approve the import. Only populated if review_state field is set.

origin git.github_pr_origin(url, use_merge=False, required_labels=[], required_status_context_names=[], required_check_runs=[], retryable_labels=[], submodules='NO', excluded_submodules=[], baseline_from_branch=False, first_parent=True, partial_fetch=False, state='OPEN', review_state=None, review_approvers=["COLLABORATOR", "MEMBER", "OWNER"], api_checker=None, patch=None, branch=None, describe_version=None, credentials=None)

Parameters:

Parameter Description
url string

Indicates the URL of the GitHub repository
use_merge bool

If the content for refs/pull/<ID>/merge should be used instead of the PR head. The GitOrigin-RevId still will be the one from refs/pull/<ID>/head revision.
required_labels sequence of string

Required labels to import the PR. All the labels need to be present in order to migrate the Pull Request.
required_status_context_names sequence of string

A list of names of services which must all mark the PR with 'success' before it can be imported.

See https://docs.github.com/en/rest/reference/repos#statuses
required_check_runs sequence of string

A list of check runs which must all have a value of 'success' in order to import the PR.

See https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api
retryable_labels sequence of string

Required labels to import the PR that should be retried. This parameter must be a subset of required_labels.
submodules string

Download submodules. Valid values: NO, YES, RECURSIVE.
excluded_submodules sequence of string

A list of names (not paths, e.g. "foo" is the submodule name if [submodule "foo"] appears in the .gitmodules file) of submodules that will not be download even if 'submodules' is set to YES or RECURSIVE.

baseline_from_branch bool

WARNING: Use this field only for github -> git CHANGE_REQUEST workflows.
When the field is set to true for CHANGE_REQUEST workflows it will find the baseline comparing the Pull Request with the base branch instead of looking for the *-RevId label in the commit message.
first_parent bool

If true, it only uses the first parent when looking for changes. Note that when disabled in ITERATIVE mode, it will try to do a migration for each change of the merged branch.
partial_fetch bool

This is an experimental feature that only works for certain origin globs.
state string

Only migrate Pull Request with that state. Possible values: 'OPEN', 'CLOSED' or 'ALL'. Default 'OPEN'
review_state string or NoneType

Required state of the reviews associated with the Pull Request Possible values:

- ANY: No review or approval required.
- HAS_REVIEWERS: A reviewer interacted with the change, e.g. commented.
- ANY_COMMIT_APPROVED: At least one commit in the PR was approved.
- HEAD_COMMIT_APPROVED: The current head commit was approved.

Default is None which has no requirement.
This field is required if the user wants GITHUB_PR_REVIEWER_APPROVER and GITHUB_PR_REVIEWER_OTHER labels populated
review_approvers sequence of string or NoneType

The set of reviewer types that are considered for approvals. In order to have any effect, review_state needs to be set. GITHUB_PR_REVIEWER_APPROVER` will be populated for these types. See the valid types here: https://developer.github.com/v4/enum/commentauthorassociation/
api_checker checker or NoneType

A checker for the GitHub API endpoint provided for after_migration hooks. This field is not required if the workflow hooks don't use the origin/destination endpoints.
patch transformation or NoneType

Patch the checkout dir. The difference with patch.apply transformation is that here we can apply it using three-way
branch string or NoneType

If set, it will only migrate pull requests for this base branch
describe_version bool or NoneType

Download tags and use 'git describe' to create four labels with a meaningful version identifier:

- GIT_DESCRIBE_CHANGE_VERSION: The version for the change or changes being migrated. The value changes per change in ITERATIVE mode and will be the latest migrated change in SQUASH (In other words, doesn't include excluded changes). this is normally what users want to use.
- GIT_DESCRIBE_REQUESTED_VERSION: git describe for the requested/head version. Constant in ITERATIVE mode and includes filtered changes.
-GIT_DESCRIBE_FIRST_PARENT: git describe for the first parent version.
-GIT_SEQUENTIAL_REVISION_NUMBER: The sequential number of the commit. Falls back to the SHA1 if not applicable.
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--allstar-app-ids list Flag used to set AllStar GitHub app id aliases. See https://github.com/ossf/allstar.
--git-fuzzy-last-rev boolean By default Copybara will try to migrate the revision listed as the version in the metadata file from github. This flag tells Copybara to first find the git tag which most closely matches the metadata version, and use that for the migration.
--git-origin-log-batch int Read the origin git log in batches of n commits. Might be needed for large migrations resulting in git logs of more than 1 GB.
--git-origin-non-linear-history boolean Read the full git log and skip changes before the from ref rather than using a log path.
--git-origin-rebase-ref string When importing a change from a Git origin ref, it will be rebased to this ref, if set. A common use case: importing a Github PR, rebase it to the main branch (usually 'master'). Note that, if the repo uses submodules, they won't be rebased.
--github-api-bearer-auth boolean If using a token for GitHub access, bearer auth might be required
--github-destination-delete-pr-branch boolean Overwrite git.github_destination delete_pr_branch field
--github-force-import boolean Force import regardless of the state of the PR
--github-pr-merge boolean Override merge bit from config
--github-required-check-run list Required check runs in the Pull Request to be imported by github_pr_origin
--github-required-label list Required labels in the Pull Request to be imported by github_pr_origin
--github-required-status-context-name list Required status context names in the Pull Request to be imported by github_pr_origin
--github-retryable-label list Required labels in the Pull Request that should be retryed to be imported by github_pr_origin
--github-skip-required-check-runs boolean Skip checking check runs for importing Pull Requests. Note that this is dangerous as it might import an unsafe PR.
--github-skip-required-labels boolean Skip checking labels for importing Pull Requests. Note that this is dangerous as it might import an unsafe PR.
--github-skip-required-status-context-names boolean Skip checking status context names for importing Pull Requests. Note that this is dangerous as it might import an unsafe PR.
--github-use-repo string Use a different git repository instead
--gql-commit-history-override list Flag used to target GraphQL params 'first' arguments in the event the defaults are over or underusing the api ratelimit. The flag value should be semicolon separated. This should be rarely used for repos that don't fit well in our defaults. E.g. '50;5;5' represent 50 commits, 5 PRs for each commit, 5 reviews per PR
--nogit-origin-version-selector boolean Disable the version selector for the migration. Only useful for forcing a migration to the passed version in the CLI

git.github_trigger

Defines a feedback trigger based on updates on a GitHub PR.

trigger git.github_trigger(url, checker=None, events=[], credentials=None)

Parameters:

Parameter Description
url string

Indicates the GitHub repo URL.
checker checker or NoneType

A checker for the GitHub API transport provided by this trigger.
events sequence of string or dict of sequence

Types of events to subscribe. Can either be a list of event types or a dict of event types to particular events of that type, e.g. ['CHECK_RUNS'] or {'CHECK_RUNS': 'my_check_run_name'}.
Valid values for event types are: 'ISSUES', 'ISSUE_COMMENT', 'PULL_REQUEST', 'PULL_REQUEST_REVIEW_COMMENT', 'PUSH', 'STATUS', 'CHECK_RUNS'
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--allstar-app-ids list Flag used to set AllStar GitHub app id aliases. See https://github.com/ossf/allstar.
--github-api-bearer-auth boolean If using a token for GitHub access, bearer auth might be required
--github-destination-delete-pr-branch boolean Overwrite git.github_destination delete_pr_branch field
--gql-commit-history-override list Flag used to target GraphQL params 'first' arguments in the event the defaults are over or underusing the api ratelimit. The flag value should be semicolon separated. This should be rarely used for repos that don't fit well in our defaults. E.g. '50;5;5' represent 50 commits, 5 PRs for each commit, 5 reviews per PR

git.integrate

Integrate changes from a url present in the migrated change label.

git_integrate git.integrate(label="COPYBARA_INTEGRATE_REVIEW", strategy="FAKE_MERGE_AND_INCLUDE_FILES", ignore_errors=True)

Parameters:

Parameter Description
label string

The migration label that will contain the url to the change to integrate.
strategy string

How to integrate the change:

  • 'FAKE_MERGE': Add the url revision/reference as parent of the migration change but ignore all the files from the url. The commit message will be a standard merge one but will include the corresponding RevId label
  • 'FAKE_MERGE_AND_INCLUDE_FILES': Same as 'FAKE_MERGE' but any change to files that doesn't match destination_files will be included as part of the merge commit. So it will be a semi fake merge: Fake for destination_files but merge for non destination files.
  • 'INCLUDE_FILES': Same as 'FAKE_MERGE_AND_INCLUDE_FILES' but it it doesn't create a merge but only include changes not matching destination_files
ignore_errors bool

If we should ignore integrate errors and continue the migration without the integrate

Example:

Integrate changes from a review url:

Assuming we have a git.destination defined like this:

git.destination(
        url = "https://example.com/some_git_repo",
        integrates = [git.integrate()],

)

It will look for COPYBARA_INTEGRATE_REVIEW label during the worklow migration. If the label is found, it will fetch the git url and add that change as an additional parent to the migration commit (merge). It will fake-merge any change from the url that matches destination_files but it will include changes not matching it.

git.latest_version

DEPRECATED: Use core.latest_version.

Customize what version of the available branches and tags to pick. By default it ignores the reference passed as parameter. Using --force in the CLI will force to use the reference passed as argument instead.

VersionSelector git.latest_version(refspec_format="refs/tags/${n0}.${n1}.${n2}", refspec_groups={'n0' : '[0-9]+', 'n1' : '[0-9]+', 'n2' : '[0-9]+'})

Parameters:

Parameter Description
refspec_format string

The format of the branch/tag
refspec_groups dict

A set of named regexes that can be used to match part of the versions. Copybara uses re2 syntax. Use the following nomenclature n0, n1, n2 for the version part (will use numeric sorting) or s0, s1, s2 (alphabetic sorting). Note that there can be mixed but the numbers cannot be repeated. In other words n0, s1, n2 is valid but not n0, s0, n1. n0 has more priority than n1. If there are fields where order is not important, use s(N+1) where N ist he latest sorted field. Example {"n0": "[0-9]+", "s1": "[a-z]+"}

git.mirror

Mirror git references between repositories

git.mirror(name, origin, destination, refspecs=['refs/heads/*'], prune=False, partial_fetch=False, description=None, action=None, origin_checker=None, destination_checker=None, origin_credentials=None, destination_credentials=None)

Parameters:

Parameter Description
name string

Migration name
origin string

Indicates the URL of the origin git repository
destination string

Indicates the URL of the destination git repository
refspecs sequence of string

Represents a list of git refspecs to mirror between origin and destination. For example 'refs/heads/:refs/remotes/origin/' will mirror any reference inside refs/heads to refs/remotes/origin.
prune bool

Remove remote refs that don't have a origin counterpart. Prune is ignored if actions are used (Action is in charge of doing the pruning)
partial_fetch bool

This is an experimental feature that only works for certain origin globs.
description string or NoneType

A description of what this migration achieves
action unknown

An action to execute when the migration is triggered. Actions can fetch, push, rebase, merge, etc. Only fetches/pushes for the declared refspec are allowed.
origin_checker checker or NoneType

Checker for applicable gerrit or github apis that can be inferred from the origin url. You can omit this if there no intention to use aforementioned APIs.
destination_checker checker or NoneType

Checker for applicable gerrit or github apis that can be inferred from the destination url. You can omit this if there no intention to use aforementioned APIs.
origin_credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag
destination_credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

git.origin

Defines a standard Git origin. For Git specific origins use: github_origin or gerrit_origin.

All the origins in this module accept several string formats as reference (When copybara is called in the form of copybara config workflow reference):

  • Branch name: For example master
  • An arbitrary reference: refs/changes/20/50820/1
  • A SHA-1: Note that it has to be reachable from the default refspec
  • A Git repository URL and reference: http://github.com/foo master
  • A GitHub pull request URL: https://github.com/some_project/pull/1784

So for example, Copybara can be invoked for a git.origin in the CLI as:
copybara copy.bara.sky my_workflow https://github.com/some_project/pull/1784
This will use the pull request as the origin URL and reference.

origin git.origin(url, ref=None, submodules='NO', excluded_submodules=[], include_branch_commit_logs=False, first_parent=True, partial_fetch=False, patch=None, describe_version=None, version_selector=None, primary_branch_migration=False, credentials=None)

Parameters:

Parameter Description
url string

Indicates the URL of the git repository
ref string or NoneType

Represents the default reference that will be used for reading the revision from the git repository. For example: 'master'
submodules string

Download submodules. Valid values: NO, YES, RECURSIVE.
excluded_submodules sequence of string

A list of names (not paths, e.g. "foo" is the submodule name if [submodule "foo"] appears in the .gitmodules file) of submodules that will not be download even if 'submodules' is set to YES or RECURSIVE.

include_branch_commit_logs bool

Whether to include raw logs of branch commits in the migrated change message.WARNING: This field is deprecated in favor of 'first_parent' one. This setting only affects merge commits.
first_parent bool

If true, it only uses the first parent when looking for changes. Note that when disabled in ITERATIVE mode, it will try to do a migration for each change of the merged branch.
partial_fetch bool

If true, partially fetch git repository by only fetching affected files.
patch transformation or NoneType

Patch the checkout dir. The difference with patch.apply transformation is that here we can apply it using three-way
describe_version bool or NoneType

Download tags and use 'git describe' to create four labels with a meaningful version identifier:

- GIT_DESCRIBE_CHANGE_VERSION: The version for the change or changes being migrated. The value changes per change in ITERATIVE mode and will be the latest migrated change in SQUASH (In other words, doesn't include excluded changes). this is normally what users want to use.
- GIT_DESCRIBE_REQUESTED_VERSION: git describe for the requested/head version. Constant in ITERATIVE mode and includes filtered changes.
-GIT_DESCRIBE_FIRST_PARENT: git describe for the first parent version.
-GIT_SEQUENTIAL_REVISION_NUMBER: The sequential number of the commit. Falls back to the SHA1 if not applicable.
version_selector VersionSelector or NoneType

Select a custom version (tag)to migrate instead of 'ref'. Version selector is expected to match the whole refspec (e.g. 'refs/heads/${n1}')
primary_branch_migration bool

When enabled, copybara will ignore the 'ref' param if it is 'master' or 'main' and instead try to establish the default git branch. If this fails, it will fall back to the 'ref' param.
This is intended to help migrating to the new standard of using 'main' without breaking users relying on the legacy default.
credentials UsernamePasswordIssuer or NoneType

EXPERIMENTAL: Read credentials from config file to access the Git Repo. This expects a 'credentials.username_password' specifying the username to use for the remote git host and a password or token. This is gated by the '--use-credentials-from-config' flag

Command line flags:

Name Type Description
--git-fuzzy-last-rev boolean By default Copybara will try to migrate the revision listed as the version in the metadata file from github. This flag tells Copybara to first find the git tag which most closely matches the metadata version, and use that for the migration.
--git-origin-log-batch int Read the origin git log in batches of n commits. Might be needed for large migrations resulting in git logs of more than 1 GB.
--git-origin-non-linear-history boolean Read the full git log and skip changes before the from ref rather than using a log path.
--git-origin-rebase-ref string When importing a change from a Git origin ref, it will be rebased to this ref, if set. A common use case: importing a Github PR, rebase it to the main branch (usually 'master'). Note that, if the repo uses submodules, they won't be rebased.
--nogit-origin-version-selector boolean Disable the version selector for the migration. Only useful for forcing a migration to the passed version in the CLI

git.review_input

Creates a review to be posted on Gerrit.

SetReviewInput git.review_input(labels={}, message=None, tag=None)

Parameters:

Parameter Description
labels dict

The labels to post.
message string or NoneType

The message to be added as review comment.
tag string or NoneType

Tag to be applied to the review, for instance 'autogenerated:copybara'.

Command line flags:

Name Type Description
--force-gerrit-submit boolean Override the gerrit submit setting that is set in the config. This also flips the submit bit.
--gerrit-change-id string ChangeId to use in the generated commit message. Use this flag if you want to reuse the same Gerrit review for an export.
--gerrit-new-change boolean Create a new change instead of trying to reuse an existing one.
--gerrit-topic string Gerrit topic to use

git.mirrorContext

Expose methods to git.mirror actions to perform operations over git repositories

Fields:

Name Description
action_name string

The name of the current action.
cli_labels dict[string, string]

Access labels that a user passes through flag '--labels'. For example: --labels=foo:value1,bar:value2. Then it can access in this way:cli_labels['foo'].
console Console

Get an instance of the console to report errors or warnings
destination_api endpoint

Returns a handle to platform specific api, inferred from the destination url when possible.
origin_api endpoint

Returns a handle to platform specific api, inferred from the origin url when possible.
params dict

Parameters for the function if created with core.action
refs sequence

A list containing string representations of the entities that triggered the event

git.mirrorContext.cherry_pick

Cherry-pick one or more commits to a branch

git_merge_result git.mirrorContext.cherry_pick(branch, commits, add_commit_origin_info=True, merge_parent_number=None, allow_empty=False, fast_forward=False)

Parameters:

Parameter Description
branch string
commits sequence of string

Commits to cherry-pick. An expression like foo..bar can be used to cherry-pick several commits. Note that 'HEAD' will refer to the branch HEAD, since cherry-pick requires a checkout of the branch before cherry-picking.
add_commit_origin_info bool

Add information about the origin of the commit (sha-1) to the message of the newcommit
merge_parent_number unknown

Specify the parent number for cherry-picking merge commits
allow_empty bool

Allow empty commits (noop commits)
fast_forward bool

Fast-forward commits if possible

git.mirrorContext.create_branch

Merge one or more commits into a local branch.

git.mirrorContext.create_branch(name, starting_point=None)

Parameters:

Parameter Description
name string
starting_point unknown

git.mirrorContext.destination_fetch

Fetch from the destination a list of refspecs. Note that fetch happens without pruning.

bool git.mirrorContext.destination_fetch(refspec, prune=True, depth=None, partial_fetch=False)

Parameters:

Parameter Description
refspec sequence of string
prune bool
depth int or NoneType

Sets number of commits to fetch. Setting to None (the default) means no limit to that number.
partial_fetch bool

If true, partially fetch only the minimum needed (e.g. don't fetch blobs if not used)

git.mirrorContext.destination_push

Push to the destination a list of refspecs.

git.mirrorContext.destination_push(refspec, prune=False, push_options=[])

Parameters:

Parameter Description
refspec sequence of string
prune bool
push_options sequence of string

Additional push options to use with destination push

git.mirrorContext.error

Returns an error action result.

dynamic.action_result git.mirrorContext.error(msg)

Parameters:

Parameter Description
msg string

The error message

git.mirrorContext.merge

Merge one or more commits into a local branch.

git_merge_result git.mirrorContext.merge(branch, commits, msg=None, fast_forward="FF")

Parameters:

Parameter Description
branch string
commits sequence of string
msg unknown
fast_forward string

Valid values are FF (default), NO_FF, FF_ONLY.

git.mirrorContext.noop

Returns a no op action result with an optional message.

dynamic.action_result git.mirrorContext.noop(msg=None)

Parameters:

Parameter Description
msg string or NoneType

The no op message

git.mirrorContext.origin_fetch

Fetch from the origin a list of refspecs. Note that fetch happens without pruning.

bool git.mirrorContext.origin_fetch(refspec, prune=True, depth=None, partial_fetch=False)

Parameters:

Parameter Description
refspec sequence of string
prune bool
depth int or NoneType

Sets number of commits to fetch. Setting to None (the default) means no limit to that number.
partial_fetch bool

If true, partially fetch only the minimum needed (e.g. don't fetch blobs if not used)

git.mirrorContext.rebase

Rebase one or more commits into a local branch.

git_merge_result git.mirrorContext.rebase(upstream, branch, newBase=None, conflict_advice=None)

Parameters:

Parameter Description
upstream string

upstream branch with new changes
branch string

Current branch with specific commits that we want to rebase in top of the new upstream changes
newBase unknown

Move the rebased changes to a new branch (--into parameter in git rebase)
conflict_advice unknown

Additional information on how to solve the issue in case if conflict

git.mirrorContext.record_effect

Records an effect of the current action.

git.mirrorContext.record_effect(summary, origin_refs, destination_ref, errors=[], type="UPDATED")

Parameters:

Parameter Description
summary string

The summary of this effect
origin_refs sequence of origin_ref

The origin refs
destination_ref destination_ref

The destination ref
errors sequence of string

An optional list of errors
type string

The type of migration effect:

  • 'CREATED': A new review or change was created.
  • 'UPDATED': An existing review or change was updated.
  • 'NOOP': The change was a noop.
  • 'NOOP_AGAINST_PENDING_CHANGE': The change was a noop, relativeto an existing pending change.
  • 'INSUFFICIENT_APPROVALS': The effect couldn't happen because the change doesn't have enough approvals.
  • 'ERROR': A user attributable error happened that prevented the destination from creating/updating the change.
  • 'STARTED': The initial effect of a migration that depends on a previous one. This allows to have 'dependant' migrations defined by users.
    An example of this: a workflow migrates code from a Gerrit review to a GitHub PR, and a feedback migration migrates the test results from a CI in GitHub back to the Gerrit change.
    This effect would be created on the former one.

git.mirrorContext.references

Return a map of reference -> sha-1 for local references matching the refspec or all if no refspec is passed.

dict[string, string] git.mirrorContext.references(refspec=[])

Parameters:

Parameter Description
refspec sequence of string

git.mirrorContext.success

Returns a successful action result.

dynamic.action_result git.mirrorContext.success()

git_merge_result

The result returned by git merge when used in Starlark. For example in git.mirror dynamic actions.

Fields:

Name Description
error bool

True if the merge execution resulted in an error. False otherwise
error_msg string

Error message from git if the merge resulted in a conflict/error. Users must check error field before accessing this field.

Returned By:

github_api_combined_status_obj

Combined Information about a commit status as defined in https://developer.github.com/v3/repos/statuses. This is a subset of the available fields in GitHub

Fields:

Name Description
sha string

The SHA-1 of the commit
state string

The overall state of all statuses for a commit: success, failure, pending or error
statuses list of github_api_status_obj

List of statuses for the commit
total_count int

Total number of statuses

Returned By:

github_api_commit_author_obj

Author/Committer for commit field for GitHub commit information https://developer.github.com/v3/git/commits/#get-a-commit. This is a subset of the available fields in GitHub

Fields:

Name Description
date string

Date of the commit
email string

Email of the author/committer
name string

Name of the author/committer

github_api_commit_obj

Commit field for GitHub commit information https://developer.github.com/v3/git/commits/#get-a-commit. This is a subset of the available fields in GitHub

Fields:

Name Description
author github_api_commit_author_obj

Author of the commit
committer github_api_commit_author_obj

Committer of the commit
message string

Message of the commit

github_api_github_commit_obj

Information about a commit as defined in https://developer.github.com/v3/git/commits/#get-a-commit. This is a subset of the available fields in GitHub

Fields:

Name Description
author github_api_user_obj

GitHub information about the author of the change
commit github_api_commit_obj

Information about the commit, like the message or git commit author/committer
committer github_api_user_obj

GitHub information about the committer of the change
html_url string

GitHub url for the commit
sha string

SHA of the commit

Returned By:

github_api_issue_comment_obj

Information about an issue comment as defined in https://docs.github.com/en/rest/issues/comments. This is a subset of the available fields in GitHub

Fields:

Name Description
body string

Body of the comment
id long

Comment identifier
user github_api_user_obj

Comment user

github_api_obj

GitHub API endpoint implementation for feedback migrations and after migration hooks.

Fields:

Name Description
url string

Return the URL of this endpoint.

github_api_obj.add_label

Add labels to a PR/issue

github_api_obj.add_label(number, labels)

Parameters:

Parameter Description
number int

Pull Request number
labels sequence of string

List of labels to add.

github_api_obj.create_issue

Create a new issue.

Issue github_api_obj.create_issue(title, body, assignees)

Parameters:

Parameter Description
title string

Title of the issue
body string

Body of the issue.
assignees sequence

GitHub users to whom the issue will be assigned.

github_api_obj.create_release

Create a new GitHub release.

github_release_obj github_api_obj.create_release(request)

Parameters:

Parameter Description
request github_create_release_obj

The populated release object. See new_release_request.

github_api_obj.create_status

Create or update a status for a commit. Returns the status created.

github_api_status_obj github_api_obj.create_status(sha, state, context, description, target_url=None)

Parameters:

Parameter Description
sha string

The SHA-1 for which we want to create or update the status
state string

The state of the commit status: 'success', 'error', 'pending' or 'failure'
context string

The context for the commit status. Use a value like 'copybara/import_successful' or similar
description string

Description about what happened
target_url string or NoneType

Url with expanded information about the event

github_api_obj.delete_reference

Delete a reference.

github_api_obj.delete_reference(ref)

Parameters:

Parameter Description
ref string

The name of the reference.

github_api_obj.get_authenticated_user

Get autenticated user info, return null if not found

github_api_user_obj github_api_obj.get_authenticated_user()

github_api_obj.get_check_runs

Get the list of check runs for a sha. https://developer.github.com/v3/checks/runs/#check-runs

list of github_check_run_obj github_api_obj.get_check_runs(sha)

Parameters:

Parameter Description
sha string

The SHA-1 for which we want to get the check runs

github_api_obj.get_combined_status

Get the combined status for a commit. Returns None if not found.

github_api_combined_status_obj github_api_obj.get_combined_status(ref)

Parameters:

Parameter Description
ref string

The SHA-1 or ref for which we want to get the combined status

github_api_obj.get_commit

Get information for a commit in GitHub. Returns None if not found.

github_api_github_commit_obj github_api_obj.get_commit(ref)

Parameters:

Parameter Description
ref string

The SHA-1 for which we want to get the combined status

github_api_obj.get_pull_request_comment

Get a pull request comment

github_api_pull_request_comment_obj github_api_obj.get_pull_request_comment(comment_id)

Parameters:

Parameter Description
comment_id string

Comment identifier

github_api_obj.get_pull_request_comments

Get all pull request comments

list of github_api_pull_request_comment_obj github_api_obj.get_pull_request_comments(number)

Parameters:

Parameter Description
number int

Pull Request number

github_api_obj.get_pull_requests

Get Pull Requests for a repo

list of github_api_pull_request_obj github_api_obj.get_pull_requests(head_prefix=None, base_prefix=None, state="OPEN", sort="CREATED", direction="ASC")

Parameters:

Parameter Description
head_prefix string or NoneType

Only return PRs wher the branch name has head_prefix
base_prefix string or NoneType

Only return PRs where the destination branch name has base_prefix
state string

State of the Pull Request. Can be "OPEN", "CLOSED" or "ALL"
sort string

Sort filter for retrieving the Pull Requests. Can be "CREATED", "UPDATED" or "POPULARITY"
direction string

Direction of the filter. Can be "ASC" or "DESC"

github_api_obj.get_reference

Get a reference SHA-1 from GitHub. Returns None if not found.

github_api_ref_obj github_api_obj.get_reference(ref)

Parameters:

Parameter Description
ref string

The name of the reference. For example: "refs/heads/branchName".

github_api_obj.get_references

Get all the reference SHA-1s from GitHub. Note that Copybara only returns a maximum number of 500.

list of github_api_ref_obj github_api_obj.get_references()

github_api_obj.list_issue_comments

Lists comments for an issue

list of github_api_issue_comment_obj github_api_obj.list_issue_comments(number)

Parameters:

Parameter Description
number int

Issue or Pull Request number

github_api_obj.new_destination_ref

Creates a new destination reference out of this endpoint.

destination_ref github_api_obj.new_destination_ref(ref, type, url=None)

Parameters:

Parameter Description
ref string

The reference.
type string

The type of this reference.
url string or NoneType

The url associated with this reference, if any.

github_api_obj.new_origin_ref

Creates a new origin reference out of this endpoint.

origin_ref github_api_obj.new_origin_ref(ref)

Parameters:

Parameter Description
ref string

The reference.

github_api_obj.new_release_request

Create a handle for creating a new release.

github_create_release_obj github_api_obj.new_release_request(tag_name)

Parameters:

Parameter Description
tag_name string

The git tag to use for the release.

Example:

Create a new release request.:

After uploading a new commit

endpoint.new_release_request(tag_name='v1.0.2').with_name('1.0.2')

github_api_obj.post_issue_comment

Post a comment on a issue.

github_api_obj.post_issue_comment(number, comment)

Parameters:

Parameter Description
number int

Issue or Pull Request number
comment string

Comment body to post.

github_api_obj.update_pull_request

Update Pull Requests for a repo. Returns None if not found

github_api_pull_request_obj github_api_obj.update_pull_request(number, title=None, body=None, state=None)

Parameters:

Parameter Description
number int

Pull Request number
title string or NoneType

New Pull Request title
body string or NoneType

New Pull Request body
state string or NoneType

State of the Pull Request. Can be "OPEN", "CLOSED"

github_api_obj.update_reference

Update a reference to point to a new commit. Returns the info of the reference.

github_api_ref_obj github_api_obj.update_reference(ref, sha, force)

Parameters:

Parameter Description
ref string

The name of the reference.
sha string

The id for the commit status.
force bool

Indicates whether to force the update or to make sure the update is a fast-forward update. Leaving this out or setting it to false will make sure you're not overwriting work. Default: false

github_api_pull_request_comment_obj

Information about a pull request comment as defined in https://developer.github.com/v3/pulls/comments/. This is a subset of the available fields in GitHub

Fields:

Name Description
body string

Body of the comment
diff_hunk string

The diff hunk where the comment was posted
id string

Comment identifier
original_position int

Original position of the comment
path string

The file path
position int

Position of the comment
user github_api_user_obj

The user who posted the comment

Returned By:

github_api_pull_request_obj

Information about a pull request as defined in https://docs.github.com/en/rest/reference/pulls. This is a subset of the available fields in GitHub

Fields:

Name Description
assignee github_api_user_obj

Pull Request assignee
base github_api_revision_obj

Information about base
body string

Pull Request body
commits int

Number of commits in the PR
draft bool

Whether pull request is a draft
head github_api_revision_obj

Information about head
merged bool

Whether pull request has been merged
number int

Pull Request number
state string

Pull Request state
title string

Pull Request title
user github_api_user_obj

Pull Request owner

Returned By:

github_api_ref_obj

Information about a commit status as defined in https://developer.github.com/v3/repos/statuses. This is a subset of the available fields in GitHub

Fields:

Name Description
ref string

The name of the reference
sha string

The sha of the reference
url string

The url of the reference

Returned By:

github_api_revision_obj

Information about a GitHub revision (Used in Pull Request and other entities)

Fields:

Name Description
label string

Label for the revision
ref string

Reference
repo Repository

Repository
sha string

SHA of the reference

github_api_status_obj

Information about a commit status as defined in https://developer.github.com/v3/repos/statuses. This is a subset of the available fields in GitHub

Fields:

Name Description
context string

Context of the commit status. This is a relatively stable id
description string

Description of the commit status. Can be None.
state string

The state of the commit status: success, failure, pending or error
target_url string

Get the target url of the commit status. Can be None.

Returned By:

github_api_user_obj

An object representing a GitHub user

Fields:

Name Description
login string

Login of the user

Returned By:

github_app_obj

Detail about a GitHub App.

Fields:

Name Description
id int

The GitHub App's Id
name string

The GitHub App's name
slug string

The url-friendly name of the GitHub App.

github_check_run_obj

Detail about a check run as defined in https://developer.github.com/v3/checks/runs/#create-a-check-run

Fields:

Name Description
app github_app_obj

The detail of a GitHub App, such as id, slug, and name
conclusion string

The final conclusion of the check. Can be one of success, failure, neutral, cancelled, timed_out, or action_required.
detail_url string

The URL of the integrator's site that has the full details of the check.
name string

The name of the check
output output_obj

The description of a GitHub App's run, including title, summary, text.
pulls list of PullRequest

Pull requests associated with this check_run ('number' only)
sha string

The SHA-1 the check run is based on
status string

The current status of the check run. Can be one of queued, in_progress, or completed.

github_check_runs_obj

List check runs for a specific ref https://developer.github.com/v3/checks/runs/#list-check-runs-for-a-specific-ref

Fields:

Name Description
check_runs list of github_check_run_obj

The list of the detail for each check run.
total_count int

The total count of check runs.

github_check_suite_obj

Detail about a check run as defined in https://developer.github.com/v3/checks/runs/#create-a-check-run

Fields:

Name Description
app github_app_obj

The detail of a GitHub App, such as id, slug, and name
conclusion string

The final conclusion of the check. Can be one of success, failure, neutral, cancelled, timed_out, or action_required.
id int

Check suite identifier
sha string

The SHA-1 the check run is based on
status string

The current status of the check run. Can be one of queued, in_progress, pending, or completed.

github_check_suites_response_obj

Detail about a check run as defined in https://docs.github.com/en/rest/checks/suites?apiVersion=2022-11-28#list-check-suites-for-a-git-reference

github_create_release_obj

GitHub API value type for release params. See https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release

Returned By:

Consumed By:

github_create_release_obj.set_draft

Is this a draft release?

github_create_release_obj github_create_release_obj.set_draft(draft)

Parameters:

Parameter Description
draft bool

Mark release as draft?

github_create_release_obj.set_generate_release_notes

Generate release notes?

github_create_release_obj github_create_release_obj.set_generate_release_notes(generate_notes)

Parameters:

Parameter Description
generate_notes bool

Generate notes?

github_create_release_obj.set_latest

Is this the latest release?

github_create_release_obj github_create_release_obj.set_latest(make_latest)

Parameters:

Parameter Description
make_latest bool

Mark release as latest?

github_create_release_obj.set_prerelease

Is this a prerelease?

github_create_release_obj github_create_release_obj.set_prerelease(prerelease)

Parameters:

Parameter Description
prerelease bool

Mark release as prerelease?

github_create_release_obj.with_body

Set the body for the release.

github_create_release_obj github_create_release_obj.with_body(body)

Parameters:

Parameter Description
body string

Body for the release

github_create_release_obj.with_commitish

Set the commitish to be used for the release. Defaults to HEAD

github_create_release_obj github_create_release_obj.with_commitish(commitish)

Parameters:

Parameter Description
commitish string

Commitish for the release

github_create_release_obj.with_name

Set the name for the release.

github_create_release_obj github_create_release_obj.with_name(name)

Parameters:

Parameter Description
name string

Name for the release

github_release_obj

GitHub API value type for a release. See https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release

Fields:

Name Description
id int

Release id
tarball string

Tarball Url
zip string

Zip Url

Returned By:

glob

A glob represents a set of relative filepaths in the Copybara workdir. Most consumers will also accept a list of fully qualified (no wildcards) file names instead.

Returned By:

Consumed By:

Globals

Global functions available in Copybara

abs

Returns the absolute value of a number (a non-negative number with the same magnitude).

abs(-2.3) == 2.3

unknown abs(x)

Parameters:

Parameter Description
x int or float

A number (int or float)

all

Returns true if all elements evaluate to True or if the collection is empty. Elements are converted to boolean using the bool function.

all(["hello", 3, True]) == True
all([-1, 0, 1]) == False

bool all(elements)

Parameters:

Parameter Description
elements unknown

A string or a collection of elements.

any

Returns true if at least one element evaluates to True. Elements are converted to boolean using the bool function.

any([-1, 0, 1]) == True
any([False, 0, ""]) == False

bool any(elements)

Parameters:

Parameter Description
elements unknown

A string or a collection of elements.

bool

Constructor for the bool type. It returns False if the object is None, False, an empty string (""), the number 0, or an empty collection (e.g. (), []). Otherwise, it returns True.

bool bool(x=False)

Parameters:

Parameter Description
x unknown

The variable to convert.

dict

Creates a dictionary from an optional positional argument and an optional set of keyword arguments. In the case where the same key is given multiple times, the last value will be used. Entries supplied via keyword arguments are considered to come after entries supplied via the positional argument.

dict dict(pairs=[], kwargs)

Parameters:

Parameter Description
pairs unknown

A dict, or an iterable whose elements are each of length 2 (key, value).
kwargs dict

Dictionary of additional entries.

dir

Returns a list of strings: the names of the attributes and methods of the parameter object.

sequence dir(x)

Parameters:

Parameter Description
x unknown

The object to check.

enumerate

Returns a list of pairs (two-element tuples), with the index (int) and the item from the input sequence.

enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]

sequence enumerate(list, start=0)

Parameters:

Parameter Description
list unknown

input sequence.
start int

start index.

fail

Causes execution to fail with an error.

fail(msg=None, attr=None, sep=" ", args)

Parameters:

Parameter Description
msg unknown

Deprecated: use positional arguments instead. This argument acts like an implicit leading positional argument.
attr string or NoneType

Deprecated. Causes an optional prefix containing this string to be added to the error message.
sep string

The separator string between the objects, default is space (" ").
args list

A list of values, formatted with debugPrint (which is equivalent to str by default) and joined with sep (defaults to " "), that appear in the error message.

float

Returns x as a float value.

  • If x is already a float, float returns it unchanged.
  • If x is a bool, float returns 1.0 for True and 0.0 for False.
  • If x is an int, float returns the nearest finite floating-point value to x, or an error if the magnitude is too large.
  • If x is a string, it must be a valid floating-point literal, or be equal (ignoring case) to NaN, Inf, or Infinity, optionally preceded by a + or - sign.
Any other value causes an error. With no argument, float() returns 0.0.

float float(x=unbound)

Parameters:

Parameter Description
x unknown

The value to convert.

getattr

Returns the struct's field of the given name if it exists. If not, it either returns default (if specified) or raises an error. getattr(x, "foobar") is equivalent to x.foobar.

getattr(ctx.attr, "myattr")
getattr(ctx.attr, "myattr", "mydefault")

unknown getattr(x, name, default=unbound)

Parameters:

Parameter Description
x unknown

The struct whose attribute is accessed.
name string

The name of the struct attribute.
default unknown

The default value to return in case the struct doesn't have an attribute of the given name.

glob

Returns an object which matches every file in the workdir that matches at least one pattern in include and does not match any of the patterns in exclude.

glob glob(include, exclude=[])

Parameters:

Parameter Description
include sequence of string

The list of glob patterns to include
exclude sequence of string

The list of glob patterns to exclude

Examples:

Simple usage:

Include all the files under a folder except for internal folder files:

glob(["foo/**"], exclude = ["foo/internal/**"])
Multiple folders:

Globs can have multiple inclusive rules:

glob(["foo/**", "bar/**", "baz/**.java"])

This will include all files inside foo and bar folders and Java files inside baz folder.

Multiple excludes:

Globs can have multiple exclusive rules:

glob(["foo/**"], exclude = ["foo/internal/**", "foo/confidential/**" ])

Include all the files of foo except the ones in internal and confidential folders

All BUILD files recursively:

Copybara uses Java globbing. The globbing is very similar to Bash one. This means that recursive globbing for a filename is a bit more tricky:

glob(["BUILD", "**/BUILD"])

This is the correct way of matching all BUILD files recursively, including the one in the root. **/BUILD would only match BUILD files in subdirectories.

Matching multiple strings with one expression:

While two globs can be used for matching two directories, there is a more compact approach:

glob(["{java,javatests}/**"])

This matches any file in java and javatests folders.

Glob union:

This is useful when you want to exclude a broad subset of files but you want to still include some of those files.

glob(["folder/**"], exclude = ["folder/**.excluded"]) + glob(['folder/includeme.excluded'])

This matches all the files in folder, excludes all files in that folder that ends with .excluded but keeps folder/includeme.excluded

+ operator for globs is equivalent to OR operation.

Glob difference:

This is another way to exclude a broad subset of files, but still include some of those files.

glob(["folder/**"]) - glob(["folder/**.excluded"], exclude=["folder/includeme.excluded"])

This matches the same file as in the previous example.

- operator for globs is equivalent to a set difference operation.

hasattr

Returns True if the object x has an attribute or method of the given name, otherwise False. Example:

hasattr(ctx.attr, "myattr")

bool hasattr(x, name)

Parameters:

Parameter Description
x unknown

The object to check.
name string

The name of the attribute.

hash

Return a hash value for a string. This is computed deterministically using the same algorithm as Java's String.hashCode(), namely: 

s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1]
Hashing of values besides strings is not currently supported.

int hash(value)

Parameters:

Parameter Description
value string

String value to hash.

int

Returns x as an int value.

  • If x is already an int, int returns it unchanged.
  • If x is a bool, int returns 1 for True and 0 for False.
  • If x is a string, it must have the format <sign><prefix><digits>. <sign> is either "+", "-", or empty (interpreted as positive). <digits> are a sequence of digits from 0 up to base - 1, where the letters a-z (or equivalently, A-Z) are used as digits for 10-35. In the case where base is 2/8/16, <prefix> is optional and may be 0b/0o/0x (or equivalently, 0B/0O/0X) respectively; if the base is any other value besides these bases or the special value 0, the prefix must be empty. In the case where base is 0, the string is interpreted as an integer literal, in the sense that one of the bases 2/8/10/16 is chosen depending on which prefix if any is used. If base is 0, no prefix is used, and there is more than one digit, the leading digit cannot be 0; this is to avoid confusion between octal and decimal. The magnitude of the number represented by the string must be within the allowed range for the int type.
  • If x is a float, int returns the integer value of the float, rounding towards zero. It is an error if x is non-finite (NaN or infinity).
This function fails if x is any other type, or if the value is a string not satisfying the above format. Unlike Python's int function, this function does not allow zero arguments, and does not allow extraneous whitespace for string arguments.

Examples:

int("123") == 123
int("-123") == -123
int("+123") == 123
int("FF", 16) == 255
int("0xFF", 16) == 255
int("10", 0) == 10
int("-0x10", 0) == -16
int("-0x10", 0) == -16
int("123.456") == 123

int int(x, base=unbound)

Parameters:

Parameter Description
x unknown

The string to convert.
base unknown

The base used to interpret a string value; defaults to 10. Must be between 2 and 36 (inclusive), or 0 to detect the base as if x were an integer literal. This parameter must not be supplied if the value is not a string.

len

Returns the length of a string, sequence (such as a list or tuple), dict, set, or other iterable.

int len(x)

Parameters:

Parameter Description
x unknown

The value whose length to report.

list

Returns a new list with the same elements as the given iterable value.

list([1, 2]) == [1, 2]
list((2, 3, 2)) == [2, 3, 2]
list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4]

sequence list(x=[])

Parameters:

Parameter Description
x sequence

The object to convert.

max

Returns the largest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable.It is an error if elements are not comparable (for example int with string), or if no arguments are given.

max(2, 5, 4) == 5
max([5, 6, 3]) == 6
max("two", "three", "four", key = len) =="three"  # the longest
max([1, -1, -2, 2], key = abs) == -2  # the first encountered with maximal key value

unknown max(key=None, args)

Parameters:

Parameter Description
key callable or NoneType

An optional function applied to each element before comparison.
args list

The elements to be checked.

min

Returns the smallest one of all given arguments. If only one positional argument is provided, it must be a non-empty iterable. It is an error if elements are not comparable (for example int with string), or if no arguments are given.

min(2, 5, 4) == 2
min([5, 6, 3]) == 3
min("six", "three", "four", key = len) == "six"  # the shortest
min([2, -2, -1, 1], key = abs) == -1  # the first encountered with minimal key value

unknown min(key=None, args)

Parameters:

Parameter Description
key callable or NoneType

An optional function applied to each element before comparison.
args list

The elements to be checked.

new_author

Create a new author from a string with the form 'name foo@bar.com'

author new_author(author_string)

Parameters:

Parameter Description
author_string string

A string representation of the author with the form 'name foo@bar.com'

Example:

Create a new author:
new_author('Foo Bar <foobar@myorg.com>')

parse_message

Returns a ChangeMessage parsed from a well formed string.

ChangeMessage parse_message(message)

Parameters:

Parameter Description
message string

The contents of the change message

print

Prints args as debug output. It will be prefixed with the string "DEBUG" and the location (file and line number) of this call. The exact way in which the arguments are converted to strings is unspecified and may change at any time. In particular, it may be different from (and more detailed than) the formatting done by str() and repr().

Using print in production code is discouraged due to the spam it creates for users. For deprecations, prefer a hard error using fail() whenever possible.

print(sep=" ", args)

Parameters:

Parameter Description
sep string

The separator string between the objects, default is space (" ").
args list

The objects to print.

range

Creates a list where items go from start to stop, using a step increment. If a single argument is provided, items will range from 0 to that element.

range(4) == [0, 1, 2, 3]
range(3, 9, 2) == [3, 5, 7]
range(3, 0, -1) == [3, 2, 1]

list of int range(start_or_stop, stop_or_none=None, step=1)

Parameters:

Parameter Description
start_or_stop int

Value of the start element if stop is provided, otherwise value of stop and the actual start is 0
stop_or_none int or NoneType

optional index of the first item not to be included in the resulting list; generation of the list stops before stop is reached.
step int

The increment (default is 1). It may be negative.

repr

Converts any object to a string representation. This is useful for debugging.

repr("ab") == '"ab"'

string repr(x)

Parameters:

Parameter Description
x unknown

The object to convert.

reversed

Returns a new, unfrozen list that contains the elements of the original iterable sequence in reversed order.

reversed([3, 5, 4]) == [4, 5, 3]

sequence reversed(sequence)

Parameters:

Parameter Description
sequence sequence

The iterable sequence (e.g. list) to be reversed.

set

Creates a new set containing the unique elements of a given iterable, preserving iteration order.

If called with no argument, set() returns a new empty set.

For example, 

set()                          # an empty set
set([3, 1, 1, 2])              # set([3, 1, 2]), a set of three elements
set({"k1": "v1", "k2": "v2"})  # set(["k1", "k2"]), a set of two elements

sequence set(elements=[])

Parameters:

Parameter Description
elements unknown

A set, a sequence of hashable values, or a dict.

sorted

Returns a new sorted list containing all the elements of the supplied iterable sequence. An error may occur if any pair of elements x, y may not be compared using x < y. The elements are sorted into ascending order, unless the reverse argument is True, in which case the order is descending. Sorting is stable: elements that compare equal retain their original relative order.

sorted([3, 5, 4]) == [3, 4, 5]
sorted([3, 5, 4], reverse = True) == [5, 4, 3]
sorted(["two", "three", "four"], key = len) == ["two", "four", "three"]  # sort by length

sequence sorted(iterable, key=None, reverse=False)

Parameters:

Parameter Description
iterable sequence

The iterable sequence to sort.
key callable or NoneType

An optional function applied to each element before comparison.
reverse bool

Return results in descending order.

str

Converts any object to string. This is useful for debugging.

str("ab") == "ab"
str(8) == "8"

string str(x)

Parameters:

Parameter Description
x unknown

The object to convert.

tuple

Returns a tuple with the same elements as the given iterable value.

tuple([1, 2]) == (1, 2)
tuple((2, 3, 2)) == (2, 3, 2)
tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4)

tuple tuple(x=())

Parameters:

Parameter Description
x sequence

The object to convert.

type

Returns the type name of its argument. This is useful for debugging and type-checking. Examples:

type(2) == "int"
type([1]) == "list"
type(struct(a = 2)) == "struct"
This function might change in the future. To write Python-compatible code and be future-proof, use it only to compare return values: 
if type(x) == type([]):  # if x is a list

string type(x)

Parameters:

Parameter Description
x unknown

The object to check type of.

zip

Returns a list of tuples, where the i-th tuple contains the i-th element from each of the argument sequences or iterables. The list has the size of the shortest input. With a single iterable argument, it returns a list of 1-tuples. With no arguments, it returns an empty list. Examples:

zip()  # == []
zip([1, 2])  # == [(1,), (2,)]
zip([1, 2], [3, 4])  # == [(1, 3), (2, 4)]
zip([1, 2], [3, 4, 5])  # == [(1, 3), (2, 4)]

sequence zip(args)

Parameters:

Parameter Description
args list

lists to zip.

go

Module for Go related starlark operations

go.go_proxy_resolver

Go resolver that knows what to do with command line passed refs.

VersionResolver go.go_proxy_resolver(module, auth=None)

Parameters:

Parameter Description
module string

The go module path name. e.g. github.com/google/gopacket. This will automatically normalize uppercase characters to '!{your_uppercase_character}' to escape them.
auth AuthInterceptor or NoneType

Optional, an interceptor for providing credentials.

go.go_proxy_version_list

Returns go proxy version list object

goproxy_version_list go.go_proxy_version_list(module, ref=None, auth=None)

Parameters:

Parameter Description
module string

The go module path name. e.g. github.com/google/gopacket. This will automatically normalize uppercase characters to '!{your_uppercase_character}' to escape them.
ref string or NoneType

This parameter is primarily used to track versions at specific branches and revisions. If a value is supplied, the returned version list will attempt to extract version data from ${ref}.info found with go proxy at the /@v/${ref}.info endpoint. You can leave off the .info suffix.
auth AuthInterceptor or NoneType

Optional, an interceptor for providing credentials.

Example:

Create a version list for a given go package:

Example of how create a version list for github.com/google/gopacket

go.go_proxy_version_list(
        module='github.com/google/gopacket'
)

goproxy_version_list

Fetch versions from goproxy

Returned By:

goproxy_version_list.get_info

Return the results of an info query. An object is only returned if a ref was specified.

GoVersionObject goproxy_version_list.get_info(ref=None)

Parameters:

Parameter Description
ref string or NoneType

The reference to query for. This is optional, and the default will be the latest version, or the ref if passed into this object during creation.

hashing

utilities for hashing

hashing.path_md5_sum

Return the md5 hash of a file at a checkout path. Do not use unless working with legacy systems that require MD5. WARNING: do not use unless working with legacy systems that require MD5

string hashing.path_md5_sum(path)

Parameters:

Parameter Description
path Path

checkout path pointing to a file to be hashed

hashing.path_sha256_sum

Return the sha256 hash of a file at a checkout path

string hashing.path_sha256_sum(path)

Parameters:

Parameter Description
path Path

checkout path pointing to a file to be hashed

hashing.str_sha256_sum

Return the hash of a list of objects based on the algorithm specified

string hashing.str_sha256_sum(input)

Parameters:

Parameter Description
input sequence of string or string

One or more string inputs to hash.

hg

Set of functions to define Mercurial (Hg) origins and destinations.

hg.origin

EXPERIMENTAL: Defines a standard Mercurial (Hg) origin.

origin hg.origin(url, ref="default")

Parameters:

Parameter Description
url string

Indicates the URL of the Hg repository
ref string

Represents the default reference that will be used to read a revision from the repository. The reference defaults to default, the most recent revision on the default branch. References can be in a variety of formats:

  • A global identifier for a revision. Example: f4e0e692208520203de05557244e573e981f6c72
  • A bookmark in the repository.
  • A branch in the repository, which returns the tip of that branch. Example: default
  • A tag in the repository. Example: tip

html

Set of functions to work with HTML in copybara

html.xpath

Run an xpath expression on HTML content to select elements. This only supports a subset of xpath expressions.

list of html_element html.xpath(content, expression)

Parameters:

Parameter Description
content string

The HTML content
expression string

XPath expression to select elements

html_element

A HTML element.

html_element.attr

Get an attribute value by key

string html_element.attr(key)

Parameters:

Parameter Description
key string

the (case-sensitive) attribute key

http

Module for working with http endpoints.

http.bearer_auth

Authentication via a bearer token.

BearerInterceptor http.bearer_auth(creds)

Parameters:

Parameter Description
creds CredentialIssuer

The token credentials.

http.endpoint

Endpoint that executes any sort of http request. Currently restrictedto requests to specific hosts.

endpoint_provider http.endpoint(host='', checker=None, hosts=[], issuers={})

Parameters:

Parameter Description
host string

DEPRECATED. A single host to allow HTTP traffic to.
checker checker or NoneType

A checker that will check calls made by the endpoint
hosts sequence

A list of hosts to allow HTTP traffic to.
issuers dict or NoneType

A dictionaty of credential issuers.

http.host

Wraps a host and potentially credentials for http auth.

HostCredential http.host(host, auth=None)

Parameters:

Parameter Description
host string

The host to be contacted.
auth AuthInterceptor or UsernamePasswordIssuer or NoneType

Optional, an interceptor for providing credentials. Also accepts a username_password.

http.json

Creates a JSON HTTP body.

HttpEndpointJsonContent http.json(body={})

Parameters:

Parameter Description
body unknown

HTTP body object, property name will be used as key and value as value.

http.multipart_form

Creates a multipart form http body.

HttpEndpointMultipartFormContent http.multipart_form(parts=[])

Parameters:

Parameter Description
parts sequence

A list of form parts

http.multipart_form_file

Create a file part for a multipart form payload.

HttpEndpointFormPart http.multipart_form_file(name, path, content_type="application/octet-stream", filename=None)

Parameters:

Parameter Description
name string

The name of the form field.
path Path

The checkout path pointing to the file to use as the field value.
content_type string

Content type header value for the form part. Defaults to application/octet-stream.
https://www.w3.org/Protocols/rfc1341/4_Content-Type.html
filename string or NoneType

The filename that will be sent along with the data. Defaults to the filename of the path parameter. Sets the filename parameter in the content disposition header.
https://www.w3.org/Protocols/HTTP/Issues/content-disposition.txt

http.multipart_form_text

Create a text/plain part for a multipart form payload

HttpEndpointFormPart http.multipart_form_text(name, text)

Parameters:

Parameter Description
name string

The name of the form field.
text string

The form value of the field

http.trigger

Trigger for http endpoint

trigger http.trigger(hosts=[], issuers={}, checker=None)

Parameters:

Parameter Description
hosts sequence

A list of hosts to allow HTTP traffic to.
issuers dict or NoneType

A dictionary of credential issuers.
checker checker or NoneType

A checker that will check calls made by the endpoint

http.url_encode

URL-encode the input string

string http.url_encode(input)

Parameters:

Parameter Description
input string

The string to be encoded.

http.urlencoded_form

Creates a url-encoded form HTTP body.

HttpEndpointUrlEncodedFormContent http.urlencoded_form(body={})

Parameters:

Parameter Description
body dict

HTTP body object, property name will be used as key and value as value.

http.username_password_auth

Authentication via username and password.

UsernamePasswordInterceptor http.username_password_auth(creds)

Parameters:

Parameter Description
creds UsernamePasswordIssuer

The username and password credentials.

http_endpoint

Calls via HTTP.

Fields:

Name Description
url string

Return the URL of this endpoint.

http_endpoint.delete

Execute a delete request

http_response http_endpoint.delete(url, headers={}, auth=False)

Parameters:

Parameter Description
url string
headers dict

dict of http headers for the request
auth bool

http_endpoint.followRedirects

Sets whether to follow redirects automatically

http_endpoint.followRedirects(followRedirects)

Parameters:

Parameter Description
followRedirects bool

Whether to follow redirects automatically

http_endpoint.get

Execute a get request

http_response http_endpoint.get(url, headers={}, auth=False)

Parameters:

Parameter Description
url string
headers dict

dict of http headers for the request
auth bool

http_endpoint.new_destination_ref

Creates a new destination reference out of this endpoint.

destination_ref http_endpoint.new_destination_ref(ref, type, url=None)

Parameters:

Parameter Description
ref string

The reference.
type string

The type of this reference.
url string or NoneType

The url associated with this reference, if any.

http_endpoint.new_origin_ref

Creates a new origin reference out of this endpoint.

origin_ref http_endpoint.new_origin_ref(ref)

Parameters:

Parameter Description
ref string

The reference.

http_endpoint.post

Execute a post request

http_response http_endpoint.post(url, headers={}, content=None, auth=False)

Parameters:

Parameter Description
url string
headers dict

dict of http headers for the request
content HttpEndpointBody or NoneType
auth bool

http_response

A http response.

Returned By:

http_response.code

http status code

int http_response.code()

http_response.contents_string

response contents as string

string http_response.contents_string()

http_response.download

Writes the content of the HTTP response into the given destination path

http_response.download(path)

Parameters:

Parameter Description
path Path

The destination Path

http_response.header

Returns the value of the response header specified by the field name

list of string http_response.header(key)

Parameters:

Parameter Description
key string

http_response.status

http status message

string http_response.status()

int

The type of integers in Starlark. Starlark integers may be of any magnitude; arithmetic is exact. Examples of integer expressions:

153
0x2A  # hexadecimal literal
0o54  # octal literal
23 * 2 + 5
100 / -7
100 % -7  # -5 (unlike in some other languages)
int("18")

Returned By:

Consumed By:

Issue

Github issue object

Fields:

Name Description
assignee github_api_user_obj

Pull Request assignee
body string

Pull Request body
number int

Pull Request number
state string

Pull Request state
title string

Pull Request title
user github_api_user_obj

Pull Request owner

Returned By:

list

The built-in list type. Example list expressions:

x = [1, 2, 3]
Accessing elements is possible using indexing (starts from 0):
e = x[1]   # e == 2
Lists support the + operator to concatenate two lists. Example:
x = [1, 2] + [3, 4]   # x == [1, 2, 3, 4]
x = ["a", "b"]
x += ["c"]            # x == ["a", "b", "c"]
Similar to strings, lists support slice operations:
['a', 'b', 'c', 'd'][1:3]   # ['b', 'c']
['a', 'b', 'c', 'd'][::2]  # ['a', 'c']
['a', 'b', 'c', 'd'][3:0:-1]  # ['d', 'c', 'b']
Lists are mutable, as in Python.

Consumed By:

list.append

Adds an item to the end of the list.

list.append(item)

Parameters:

Parameter Description
item unknown

Item to add at the end.

list.clear

Removes all the elements of the list.

list.clear()

list.extend

Adds all items to the end of the list.

list.extend(items)

Parameters:

Parameter Description
items unknown

Items to add at the end.

list.index

Returns the index in the list of the first item whose value is x. It is an error if there is no such item.

int list.index(x, start=None, end=None)

Parameters:

Parameter Description
x unknown

The object to search.
start int or NoneType

The start index of the list portion to inspect.
end int or NoneType

The end index of the list portion to inspect.

list.insert

Inserts an item at a given position.

list.insert(index, item)

Parameters:

Parameter Description
index int

The index of the given position.
item unknown

The item.

list.pop

Removes the item at the given position in the list, and returns it. If no index is specified, it removes and returns the last item in the list.

unknown list.pop(i=-1)

Parameters:

Parameter Description
i int or NoneType

The index of the item.

list.remove

Removes the first item from the list whose value is x. It is an error if there is no such item.

list.remove(x)

Parameters:

Parameter Description
x unknown

The object to remove.

mapping_function

A function that given an object can map to another object

Returned By:

metadata

Core transformations for the change metadata

metadata.add_header

Adds a header line to the commit message. Any variable present in the message in the form of ${LABEL_NAME} will be replaced by the corresponding label in the message. Note that this requires that the label is already in the message or in any of the changes being imported. The label in the message takes priority over the ones in the list of original messages of changes imported.

transformation metadata.add_header(text, ignore_label_not_found=False, new_line=True)

Parameters:

Parameter Description
text string

The header text to include in the message. For example '[Import of foo ${LABEL}]'. This would construct a message resolving ${LABEL} to the corresponding label.
ignore_label_not_found bool

If a label used in the template is not found, ignore the error and don't add the header. By default it will stop the migration and fail.
new_line bool

If a new line should be added between the header and the original message. This allows to create messages like HEADER: ORIGINAL_MESSAGE

Examples:

Add a header always:

Adds a header to any message

metadata.add_header("COPYBARA CHANGE")

Messages like:

A change

Example description for
documentation

Will be transformed into:

COPYBARA CHANGE
A change

Example description for
documentation
Add a header that uses a label:

Adds a header to messages that contain a label. Otherwise it skips the message manipulation.

metadata.add_header("COPYBARA CHANGE FOR https://github.com/myproject/foo/pull/${GITHUB_PR_NUMBER}",
    ignore_label_not_found = True,
)

A change message, imported using git.github_pr_origin, like:

A change

Example description for
documentation

Will be transformed into:

COPYBARA CHANGE FOR https://github.com/myproject/foo/pull/1234
Example description for
documentation

Assuming the PR number is 1234. But any change without that label will not be transformed.

Add a header without new line:

Adds a header without adding a new line before the original message:

metadata.add_header("COPYBARA CHANGE: ", new_line = False)

Messages like:

A change

Example description for
documentation

Will be transformed into:

COPYBARA CHANGE: A change

Example description for
documentation

metadata.expose_label

Certain labels are present in the internal metadata but are not exposed in the message by default. This transformations find a label in the internal metadata and exposes it in the message. If the label is already present in the message it will update it to use the new name and separator.

transformation metadata.expose_label(name, new_name=label, separator="=", ignore_label_not_found=True, all=False, concat_separator=None)

Parameters:

Parameter Description
name string

The label to search
new_name string or NoneType

The name to use in the message
separator string

The separator to use when adding the label to the message
ignore_label_not_found bool

If a label is not found, ignore the error and continue.
all bool

By default Copybara tries to find the most relevant instance of the label. First looking into the message and then looking into the changes in order. If this field is true it exposes all the matches instead.
concat_separator unknown

If all is set, copybara will expose multiple values in one per line. If a separator is specified, it will concat the values instead.

Examples:

Simple usage:

Expose a hidden label called 'REVIEW_URL':

metadata.expose_label('REVIEW_URL')

This would add it as REVIEW_URL=the_value.

New label name:

Expose a hidden label called 'REVIEW_URL' as GIT_REVIEW_URL:

metadata.expose_label('REVIEW_URL', 'GIT_REVIEW_URL')

This would add it as GIT_REVIEW_URL=the_value.

Custom separator:

Expose the label with a custom separator

metadata.expose_label('REVIEW_URL', separator = ': ')

This would add it as REVIEW_URL: the_value.

Expose multiple labels:

Expose all instances of a label in all the changes (SQUASH for example)

metadata.expose_label('REVIEW_URL', all = True)

This would add 0 or more REVIEW_URL: the_value labels to the message.

Expose multiple labels, concatenating the values :

Expose all instances of a label in all the changes (SQUASH for example)

metadata.expose_label('REVIEW_URL', all = True, concat_separator=',')

This would add a REVIEW_URL: value1,value2 label to the message.

metadata.map_author

Map the author name and mail to another author. The mapping can be done by both name and mail or only using any of the two.

transformation metadata.map_author(authors, reversible=False, noop_reverse=False, fail_if_not_found=False, reverse_fail_if_not_found=False, map_all_changes=False)

Parameters:

Parameter Description
authors dict

The author mapping. Keys can be in the form of 'Your Name', 'some@mail' or 'Your Name <some@mail>'. The mapping applies heuristics to know which field to use in the mapping. The value has to be always in the form of 'Your Name <some@mail>'
reversible bool

If the transform is automatically reversible. Workflows using the reverse of this transform will be able to automatically map values to keys.
noop_reverse bool

If true, the reversal of the transformation doesn't do anything. This is useful to avoid having to write core.transformation(metadata.map_author(...), reversal = []).
fail_if_not_found bool

Fail if a mapping cannot be found. Helps discovering early authors that should be in the map
reverse_fail_if_not_found bool

Same as fail_if_not_found but when the transform is used in a inverse workflow.
map_all_changes bool

If all changes being migrated should be mapped. Useful for getting a mapped metadata.squash_notes. By default we only map the current author.

Example:

Map some names, emails and complete authors:

Here we show how to map authors using different options:

metadata.map_author({
    'john' : 'Some Person <some@example.com>',
    'madeupexample@google.com' : 'Other Person <someone@example.com>',
    'John Example <john.example@example.com>' : 'Another Person <some@email.com>',
})

metadata.map_references

Allows updating links to references in commit messages to match the destination's format. Note that this will only consider the 5000 latest commits.

transformation metadata.map_references(before, after, regex_groups={}, additional_import_labels=[])

Parameters:

Parameter Description
before string

Template for origin references in the change message. Use a '${reference}' token to capture the actual references. E.g. if the origin uses links like 'http://changes?1234', the template would be 'http://changes?${reference}', with reference_regex = '[0-9]+'
after string

Format for destination references in the change message. Use a '${reference}' token to represent the destination reference. E.g. if the destination uses links like 'http://changes?1234', the template would be 'http://changes?${reference}', with reference_regex = '[0-9]+'
regex_groups dict

Regexes for the ${reference} token's content. Requires one 'before_ref' entry matching the ${reference} token's content on the before side. Optionally accepts one 'after_ref' used for validation. Copybara uses re2 syntax.
additional_import_labels sequence of string

Meant to be used when migrating from another tool: Per default, copybara will only recognize the labels defined in the workflow's endpoints. The tool will use these additional labels to find labels created by other invocations and tools.

Example:

Map references, origin source of truth:

Finds links to commits in change messages, searches destination to find the equivalent reference in destination. Then replaces matches of 'before' with 'after', replacing the subgroup matched with the destination reference. Assume a message like 'Fixes bug introduced in origin/abcdef', where the origin change 'abcdef' was migrated as '123456' to the destination.

metadata.map_references(
    before = "origin/${reference}",
    after = "destination/${reference}",
    regex_groups = {
        "before_ref": "[0-9a-f]+",
        "after_ref": "[0-9]+",
    },
)

This would be translated into 'Fixes bug introduced in destination/123456', provided that a change with the proper label was found - the message remains unchanged otherwise.

metadata.remove_label

Remove a label from the message

transformation metadata.remove_label(name)

Parameters:

Parameter Description
name string

The label name

Example:

Remove a label:

Remove Change-Id label from the message:

metadata.remove_label('Change-Id')

metadata.replace_message

Replace the change message with a template text. Any variable present in the message in the form of ${LABEL_NAME} will be replaced by the corresponding label in the message. Note that this requires that the label is already in the message or in any of the changes being imported. The label in the message takes priority over the ones in the list of original messages of changes imported.

transformation metadata.replace_message(text, ignore_label_not_found=False)

Parameters:

Parameter Description
text string

The template text to use for the message. For example '[Import of foo ${LABEL}]'. This would construct a message resolving ${LABEL} to the corresponding label.
ignore_label_not_found bool

If a label used in the template is not found, ignore the error and don't add the header. By default it will stop the migration and fail.

Example:

Replace the message:

Replace the original message with a text:

metadata.replace_message("COPYBARA CHANGE: Import of ${GITHUB_PR_NUMBER}\n\n${GITHUB_PR_BODY}\n")

Will transform the message to:

COPYBARA CHANGE: Import of 12345

Body from Github Pull Request

metadata.restore_author

For a given change, restore the author present in the ORIGINAL_AUTHOR label as the author of the change.

transformation metadata.restore_author(label='ORIGINAL_AUTHOR', separator="=", search_all_changes=False)

Parameters:

Parameter Description
label string

The label to use for restoring the author
separator string

The separator to use between the label and the value
search_all_changes bool

By default Copybara only looks in the last current change for the author label. This allows to do the search in all current changes (Only makes sense for SQUASH/CHANGE_REQUEST).

metadata.save_author

For a given change, store a copy of the author as a label with the name ORIGINAL_AUTHOR.

transformation metadata.save_author(label='ORIGINAL_AUTHOR', separator="=")

Parameters:

Parameter Description
label string

The label to use for storing the author
separator string

The separator to use between the label and the value

metadata.scrubber

Removes part of the change message using a regex

transformation metadata.scrubber(regex, msg_if_no_match=None, fail_if_no_match=False, replacement='')

Parameters:

Parameter Description
regex string

Any text matching the regex will be removed. Note that the regex is runs in multiline mode.
msg_if_no_match string or NoneType

If set, Copybara will use this text when the scrubbing regex doesn't match.
fail_if_no_match bool

If set, msg_if_no_match must be None and then fail if the scrubbing regex doesn't match.

replacement string

Text replacement for the matching substrings. References to regex group numbers can be used in the form of $1, $2, etc.

Examples:

Remove from a keyword to the end of the message:

When change messages are in the following format:

Public change description

This is a public description for a commit

CONFIDENTIAL:
This fixes internal project foo-bar

Using the following transformation:

metadata.scrubber('(^|\n)CONFIDENTIAL:(.|\n)*')

Will remove the confidential part, leaving the message as:

Public change description

This is a public description for a commit
Keep only message enclosed in tags:

The previous example is prone to leak confidential information since a developer could easily forget to include the CONFIDENTIAL label. A different approach for this is to scrub everything by default except what is explicitly allowed. For example, the following scrubber would remove anything not enclosed in <public></public> tags:

metadata.scrubber('^(?:\n|.)*<public>((?:\n|.)*)</public>(?:\n|.)*$', replacement = '$1')

So a message like:

this
is
very confidential<public>but this is public
very public
</public>
and this is a secret too

would be transformed into:

but this is public
very public
Use default msg when the scrubbing regex doesn't match:

Assign msg_if_no_match a default msg. For example:

metadata.scrubber('^(?:\n|.)*<public>((?:\n|.)*)</public>(?:\n|.)*$', msg_if_no_match = 'Internal Change.', replacement = '$1')

So a message like:

this
is
very confidential
This is not public msg.

and this is a secret too

would be transformed into:

Internal Change.
Fail if the scrubbing regex doesn't match:

Set fail_if_no_match to true

metadata.scrubber('^(?:\n|.)*<public>((?:\n|.)*)</public>(?:\n|.)*$', fail_if_no_match = True, replacement = '$1')

So a message like:

this
is
very confidential
but this is not public

and this is a secret too

This would fail. Error msg:

Scrubber regex: '^(?:\n|.)*<public>((?:\n|.)*)</public>(?:\n|.)*$' didn't match for description: this
is
very confidential
but this is not public

and this is a secret too

metadata.squash_notes

Generate a message that includes a constant prefix text and a list of changes included in the squash change.

transformation metadata.squash_notes(prefix='Copybara import of the project:\n\n', max=100, compact=True, show_ref=True, show_author=True, show_description=True, oldest_first=False, use_merge=True)

Parameters:

Parameter Description
prefix string

A prefix to be printed before the list of commits.
max int

Max number of commits to include in the message. For the rest a comment like (and x more) will be included. By default 100 commits are included.
compact bool

If compact is set, each change will be shown in just one line
show_ref bool

If each change reference should be present in the notes
show_author bool

If each change author should be present in the notes
show_description bool

If each change description should be present in the notes
oldest_first bool

If set to true, the list shows the oldest changes first. Otherwise it shows the changes in descending order.
use_merge bool

If true then merge changes are included in the squash notes

Examples:

Simple usage:

'Squash notes' default is to print one line per change with information about the author

metadata.squash_notes("Changes for Project Foo:\n")

This transform will generate changes like:

Changes for Project Foo:

  - 1234abcde second commit description by Foo Bar <foo@bar.com>
  - a4321bcde first commit description by Foo Bar <foo@bar.com>
Removing authors and reversing the order:
metadata.squash_notes("Changes for Project Foo:\n",
    oldest_first = True,
    show_author = False,
)

This transform will generate changes like:

Changes for Project Foo:

  - a4321bcde first commit description
  - 1234abcde second commit description
Removing description:
metadata.squash_notes("Changes for Project Foo:\n",
    show_description = False,
)

This transform will generate changes like:

Changes for Project Foo:

  - a4321bcde by Foo Bar <foo@bar.com>
  - 1234abcde by Foo Bar <foo@bar.com>
Showing the full message:
metadata.squash_notes(
  prefix = 'Changes for Project Foo:',
  compact = False
)

This transform will generate changes like:

Changes for Project Foo:
--
2 by Foo Baz <foo@baz.com>:

second commit

Extended text
--
1 by Foo Bar <foo@bar.com>:

first commit

Extended text

metadata.use_last_change

Use metadata (message or/and author) from the last change being migrated. Useful when using 'SQUASH' mode but user only cares about the last change.

transformation metadata.use_last_change(author=True, message=True, default_message=None, use_merge=True)

Parameters:

Parameter Description
author bool

Replace author with the last change author (Could still be the default author if not on the allowlist or using authoring.overwrite.)
message bool

Replace message with last change message.
default_message string or NoneType

Replace message with last change message.
use_merge bool

If true then merge changes are taken into account for looking for the last change.

metadata.verify_match

Verifies that a RegEx matches (or not matches) the change message. Does not transform anything, but will stop the workflow if it fails.

transformation metadata.verify_match(regex, verify_no_match=False)

Parameters:

Parameter Description
regex string

The regex pattern to verify. The re2j pattern will be applied in multiline mode, i.e. '^' refers to the beginning of a file and '$' to its end.
verify_no_match bool

If true, the transformation will verify that the RegEx does not match.

Example:

Check that a text is present in the change description:

Check that the change message contains a text enclosed in <public></public>:

metadata.verify_match("<public>(.|\n)*</public>")

origin

A Origin represents a source control repository from which source is copied.

Returned By:

Consumed By:

origin_ref

Reference to the change/review in the origin.

Fields:

Name Description
ref string

Origin reference ref

Returned By:

Consumed By:

output_obj

Descriptive details about the run.

Fields:

Name Description
summary string

The summary of the check run.
text string

The details of the check run.
title string

The title of the check run.

patch

Module for applying patches.

patch.apply

A transformation that applies the given patch files. If a path does not exist in a patch, it will be ignored.

transformation patch.apply(patches=[], excluded_patch_paths=[], series=None, strip=1, directory='')

Parameters:

Parameter Description
patches sequence of string

The list of patchfiles to apply, relative to the current config file. The files will be applied relative to the checkout dir and the leading path component will be stripped (-p1).

If series is also specified, these patches will be applied before those ones.

This field doesn't accept a glob.
excluded_patch_paths sequence of string

The list of paths to exclude from each of the patches. Each of the paths will be excluded from all the patches. Note that these are not workdir paths, but paths relative to the patch itself. If not empty, the patch will be applied using 'git apply' instead of GNU Patch.
series string or NoneType

A file which contains a list of patches to apply. The patch files to apply are interpreted relative to this file and must be written one per line. The patches listed in this file will be applied relative to the checkout dir and the leading path component will be stripped (via the -p1 flag).

You can generate a file which matches this format by running 'find . -name *.patch | sort > series'.

If patches is also specified, those patches will be applied before these ones.
strip int

Number of segments to strip. (This sets the -pX flag, for example -p0, -p1, etc.) By default it uses -p1.
directory string

Path relative to the working directory from which to apply patches. This supports patches that specify relative paths in their file diffs but use a different relative path base than the working directory. (This sets the -d flag, for example -d sub/dir/). By default, it uses the current directory.

Command line flags:

Name Type Description
--patch-skip-version-check boolean Skip checking the version of patch and assume it is fine
--patch-use-git-apply boolean Don't use GNU Patch and instead use 'git apply'
--quilt-bin string Path to quilt command

patch.quilt_apply

A transformation that applies and updates patch files using Quilt. Compared to patch.apply, this transformation supports updating the content of patch files if they can be successfully applied with fuzz. The patch files must be included in the destination_files glob in order to get updated. Underneath, Copybara runs quilt import; quilt push; quilt refresh for each patch file in the series file in order. Currently, all patch files and the series file must reside in a "patches" sub-directory under the root directory containing the migrated code. This means it has the limitation that the migrated code itself cannot contain a directory with the name "patches".

transformation patch.quilt_apply(series)

Parameters:

Parameter Description
series string

A file which contains a list of patches to apply. It is similar to the series parameter in patch.apply transformation, and is required for Quilt. Patches listed in this file will be applied relative to the checkout dir, and the leading path component is stripped via the -p1 flag. Currently this file should be the patches/series file in the root directory of the migrated code.

Example:

Workflow to apply and update patches:

Suppose the destination repository's directory structure looks like:

source_root/BUILD
source_root/copy.bara.sky
source_root/migrated_file1
source_root/migrated_file2
source_root/patches/series
source_root/patches/patch1.patch

Then the transformations in source_root/copy.bara.sky should look like:

[
    patch.quilt_apply(series = "patches/series"),
    core.move("", "source_root"),
]

In this example, patch1.patch is applied to migrated_file1 and/or migrated_file2. patch1.patch itself will be updated during the migration if it is applied with fuzz.

Command line flags:

Name Type Description
--patch-skip-version-check boolean Skip checking the version of patch and assume it is fine
--patch-use-git-apply boolean Don't use GNU Patch and instead use 'git apply'
--quilt-bin string Path to quilt command

Path

Represents a path in the checkout directory

Fields:

Name Description
attr PathAttributes

Get the file attributes, for example size.
name string

Filename of the path. For foo/bar/baz.txt it would be baz.txt
parent unknown

Get the parent path
path string

Full path relative to the checkout directory

Returned By:

Consumed By:

path.exists

Check whether a file, directory or symlink exists at this path

bool path.exists()

path.read_symlink

Read the symlink

Path path.read_symlink()

path.relativize

Constructs a relative path between this path and a given path. For example:
path('a/b').relativize('a/b/c/d')
returns 'c/d'

Path path.relativize(other)

Parameters:

Parameter Description
other Path

The path to relativize against this path

path.remove

Delete self

path.remove()

path.resolve

Resolve the given path against this path.

Path path.resolve(child)

Parameters:

Parameter Description
child string or Path

Resolve the given path against this path. The parameter can be a string or a Path.

path.resolve_sibling

Resolve the given path against this path.

Path path.resolve_sibling(other)

Parameters:

Parameter Description
other string or Path

Resolve the given path against this path. The parameter can be a string or a Path.

path.rmdir

Delete all files in a directory. If recursive is true, delete descendants of all files in directory

path.rmdir(recursive=False)

Parameters:

Parameter Description
recursive bool

When true, delete descendants of self and of siblings

PathAttributes

Represents a path attributes like size.

Fields:

Name Description
size int

The size of the file. Throws an error if file size > 2GB.
symlink bool

Returns true if it is a symlink

python

utilities for interacting with the pypi package manager

python.parse_metadata

Extract the metadata from a python METADATA file into a dictionary. Returns a list of key value tuples.

list of tuple python.parse_metadata(path)

Parameters:

Parameter Description
path Path

path relative to workdir root of the .whl file

random

A module for randomization-related functions.

random.sample

Returns a list of k unique elements randomly sampled from the list.

sequence random.sample(population, k)

Parameters:

Parameter Description
population list

The list to sample from.
k int

The number of elements to sample from the population list.

re2

Set of functions to work with regexes in Copybara.

re2.compile

Create a regex pattern

re2_pattern re2.compile(regex)

Parameters:

Parameter Description
regex string

Example:

Simple regex:

Patterns need to be compiled before using them:

re2.compile("a(.*)b").matches('accccb')

re2.quote

Quote a string to be matched literally if used within a regex pattern

string re2.quote(string)

Parameters:

Parameter Description
string string

re2_matcher

A RE2 regex pattern matcher object to perform regexes in Starlark

Returned By:

re2_matcher.end

Return the end position of a matching group

int re2_matcher.end(group=0)

Parameters:

Parameter Description
group int or string

re2_matcher.find

Return true if the string matches the regex pattern.

bool re2_matcher.find(start=None)

Parameters:

Parameter Description
start int or NoneType

The input position where the search begins

re2_matcher.group

Return a matching group

string re2_matcher.group(group=0)

Parameters:

Parameter Description
group int or string

re2_matcher.group_count

Return the number of groups found for a match

int re2_matcher.group_count()

re2_matcher.matches

Return true if the string matches the regex pattern.

bool re2_matcher.matches()

re2_matcher.replace_all

Replace all instances matching the regex

string re2_matcher.replace_all(replacement=0)

Parameters:

Parameter Description
replacement string

re2_matcher.replace_first

Replace the first instance matching the regex

string re2_matcher.replace_first(replacement=0)

Parameters:

Parameter Description
replacement string

re2_matcher.start

Return the start position of a matching group

int re2_matcher.start(group=0)

Parameters:

Parameter Description
group int or string

re2_pattern

A RE2 regex pattern object to perform regexes in Starlark

Returned By:

re2_pattern.matcher

Return a Matcher for the given input.

re2_matcher re2_pattern.matcher(input)

Parameters:

Parameter Description
input string

re2_pattern.matches

Return true if the string matches the regex pattern

bool re2_pattern.matches(input)

Parameters:

Parameter Description
input string

remotefiles

Functions to access remote files not in either repo.

Command line flags:

Name Type Description
--remote-http-files-connection-timeout duration Timeout for the fetch operation, e.g. 30s. Example values: 30s, 20m, 1h, etc.

remotefiles.origin

Defines a remote file origin.

origin remotefiles.origin(author='Copybara noreply@copybara.io', message='Placeholder message', unpack_method='AS_IS', archive_source='', version_list=None, origin_version_selector=None, version_resolver=None, auth=None)

Parameters:

Parameter Description
author string

Author to attribute the change to
message string

Message to attach to the change
unpack_method string

The method by which to unpack the remote file. Currently 'ZIP', 'TAR', 'TAR_GZ', 'TAR_XZ' and 'AS_IS' are supported.
archive_source string

Template or literal URL to download archive from. Optionally you can use ${VERSION} in your URL string as placeholder for later resolved versions during origin checkout. E.g. 'https://proxy.golang.org/mymodule/@v/${VERSION}.zip'
version_list VersionList or NoneType

Version list to select versions on. Omit to create a versionless origin.
origin_version_selector VersionSelector or NoneType

Version selector used to select on version_list. Omit to create a versionless origin.
version_resolver VersionResolver or NoneType

Version resolvers are used to resolve refs to specific versions. Primarily used when command line refs are provided and accompanied by the '--force' or '--version-selector-use-cli-ref' flag.
auth AuthInterceptor or NoneType

Optional, an interceptor for providing credentials.

Command line flags:

Name Type Description
--remote-http-files-connection-timeout duration Timeout for the fetch operation, e.g. 30s. Example values: 30s, 20m, 1h, etc.

rust_version_requirement

Represents a Cargo version requirement.

rust_version_requirement.fulfills

Given a semantic version string, returns true if the version fulfills this version requirement.

bool rust_version_requirement.fulfills(fulfills)

Parameters:

Parameter Description
fulfills string

The version requirement

set

The built-in set type. A set is a mutable, iterable collection of unique values – the set's elements. The type name of a set is "set".

Sets provide constant-time operations to insert, remove, or check for the presence of a value. Sets are implemented using a hash table, and therefore, just like keys of a dictionary, elements of a set must be hashable. A value may be used as an element of a set if and only if it may be used as a key of a dictionary.

Sets may be constructed using the set() built-in function, which returns a new set containing the unique elements of its optional argument, which must be an iterable. Calling set() without an argument constructs an empty set. Sets have no literal syntax.

The in and not in operations check whether a value is (or is not) in a set: 

s = set(["a", "b", "c"])
"a" in s  # True
"z" in s  # False

A set is iterable, and thus may be used as the operand of a for loop, a list comprehension, and the various built-in functions that operate on iterables. Its length can be retrieved using the len() built-in function, and the order of iteration is the order in which elements were first added to the set: 

s = set(["z", "y", "z", "y"])
len(s)       # prints 2
s.add("x")
len(s)       # prints 3
for e in s:
    print e  # prints "z", "y", "x"

A set used in Boolean context is true if and only if it is non-empty. 

s = set()
"non-empty" if s else "empty"  # "empty"
t = set(["x", "y"])
"non-empty" if t else "empty"  # "non-empty"

Sets may be compared for equality or inequality using == and !=. A set s is equal to t if and only if t is a set containing the same elements; iteration order is not significant. In particular, a set is not equal to the list of its elements. Sets are not ordered with respect to other sets, and an attempt to compare two sets using <, <=, >, >=, or to sort a sequence of sets, will fail. 

set() == set()              # True
set() != []                 # True
set([1, 2]) == set([2, 1])  # True
set([1, 2]) != [1, 2]       # True

The | operation on two sets returns the union of the two sets: a set containing the elements found in either one or both of the original sets. 

set([1, 2]) | set([3, 2])  # set([1, 2, 3])

The & operation on two sets returns the intersection of the two sets: a set containing only the elements found in both of the original sets. 

set([1, 2]) & set([2, 3])  # set([2])
set([1, 2]) & set([3, 4])  # set()

The - operation on two sets returns the difference of the two sets: a set containing the elements found in the left-hand side set but not the right-hand side set. 

set([1, 2]) - set([2, 3])  # set([1])
set([1, 2]) - set([3, 4])  # set([1, 2])

The ^ operation on two sets returns the symmetric difference of the two sets: a set containing the elements found in exactly one of the two original sets, but not in both. 

set([1, 2]) ^ set([2, 3])  # set([1, 3])
set([1, 2]) ^ set([3, 4])  # set([1, 2, 3, 4])

In each of the above operations, the elements of the resulting set retain their order from the two operand sets, with all elements that were drawn from the left-hand side ordered before any element that was only present in the right-hand side.

The corresponding augmented assignments, |=, &=, -=, and ^=, modify the left-hand set in place. 

s = set([1, 2])
s |= set([2, 3, 4])     # s now equals set([1, 2, 3, 4])
s &= set([0, 1, 2, 3])  # s now equals set([1, 2, 3])
s -= set([0, 1])        # s now equals set([2, 3])
s ^= set([3, 4])        # s now equals set([2, 4])

Like all mutable values in Starlark, a set can be frozen, and once frozen, all subsequent operations that attempt to update it will fail.

set.add

Adds an element to the set.

It is permissible to add a value already present in the set; this leaves the set unchanged.

If you need to add multiple elements to a set, see update or the |= augmented assignment operation.

set.add(element)

Parameters:

Parameter Description
element ?

Element to add.

set.clear

Removes all the elements of the set.

set.clear()

set.difference

Returns a new mutable set containing the difference of this set with others.

If s and t are sets, s.difference(t) is equivalent to s - t; however, note that the - operation requires both sides to be sets, while the difference method also accepts sequences and dicts.

It is permissible to call difference without any arguments; this returns a copy of the set.

For example, 

set([1, 2, 3]).difference([2])             # set([1, 3])
set([1, 2, 3]).difference([0, 1], [3, 4])  # set([2])

sequence set.difference(others)

Parameters:

Parameter Description
others list

Sets, sequences of hashable elements, or dicts.

set.difference_update

Removes any elements found in any others from this set.

If s and t are sets, s.difference_update(t) is equivalent to s -= t; however, note that the -= augmented assignment requires both sides to be sets, while the difference_update method also accepts sequences and dicts.

It is permissible to call difference_update without any arguments; this leaves the set unchanged.

For example, 

s = set([1, 2, 3, 4])
s.difference_update([2])             # None; s is set([1, 3, 4])
s.difference_update([0, 1], [4, 5])  # None; s is set([3])

set.difference_update(others)

Parameters:

Parameter Description
others list

Sets, sequences of hashable elements, or dicts.

set.discard

Removes an element from the set if it is present.

It is permissible to discard a value not present in the set; this leaves the set unchanged. If you want to fail on an attempt to remove a non-present element, use remove instead. If you need to remove multiple elements from a set, see difference_update or the -= augmented assignment operation.

For example, 

s = set(["x", "y"])
s.discard("y")  # None; s == set(["x"])
s.discard("y")  # None; s == set(["x"])

set.discard(element)

Parameters:

Parameter Description
element ?

Element to discard. Must be hashable.

set.intersection

Returns a new mutable set containing the intersection of this set with others.

If s and t are sets, s.intersection(t) is equivalent to s & t; however, note that the & operation requires both sides to be sets, while the intersection method also accepts sequences and dicts.

It is permissible to call intersection without any arguments; this returns a copy of the set.

For example, 

set([1, 2]).intersection([2, 3])             # set([2])
set([1, 2, 3]).intersection([0, 1], [1, 2])  # set([1])

sequence set.intersection(others)

Parameters:

Parameter Description
others list

Sets, sequences of hashable elements, or dicts.

set.intersection_update

Removes any elements not found in all others from this set.

If s and t are sets, s.intersection_update(t) is equivalent to s &= t; however, note that the &= augmented assignment requires both sides to be sets, while the intersection_update method also accepts sequences and dicts.

It is permissible to call intersection_update without any arguments; this leaves the set unchanged.

For example, 

s = set([1, 2, 3, 4])
s.intersection_update([0, 1, 2])       # None; s is set([1, 2])
s.intersection_update([0, 1], [1, 2])  # None; s is set([1])

set.intersection_update(others)

Parameters:

Parameter Description
others list

Sets, sequences of hashable elements, or dicts.

set.isdisjoint

Returns true if this set has no elements in common with another.

For example, 

set([1, 2]).isdisjoint([3, 4])  # True
set().isdisjoint(set())         # True
set([1, 2]).isdisjoint([2, 3])  # False

bool set.isdisjoint(other)

Parameters:

Parameter Description
other unknown

A set, a sequence of hashable elements, or a dict.

set.issubset

Returns true of this set is a subset of another.

Note that a set is always considered to be a subset of itself.

For example, 

set([1, 2]).issubset([1, 2, 3])  # True
set([1, 2]).issubset([1, 2])     # True
set([1, 2]).issubset([2, 3])     # False

bool set.issubset(other)

Parameters:

Parameter Description
other unknown

A set, a sequence of hashable elements, or a dict.

set.issuperset

Returns true of this set is a superset of another.

Note that a set is always considered to be a superset of itself.

For example, 

set([1, 2, 3]).issuperset([1, 2])     # True
set([1, 2, 3]).issuperset([1, 2, 3])  # True
set([1, 2, 3]).issuperset([2, 3, 4])  # False

bool set.issuperset(other)

Parameters:

Parameter Description
other unknown

A set, a sequence of hashable elements, or a dict.

set.pop

Removes and returns the first element of the set (in iteration order, which is the order in which elements were first added to the set).

Fails if the set is empty.

For example, 

s = set([3, 1, 2])
s.pop()  # 3; s == set([1, 2])
s.pop()  # 1; s == set([2])
s.pop()  # 2; s == set()
s.pop()  # error: empty set

? set.pop()

set.remove

Removes an element, which must be present in the set, from the set.

remove fails if the element was not present in the set. If you don't want to fail on an attempt to remove a non-present element, use discard instead. If you need to remove multiple elements from a set, see difference_update or the -= augmented assignment operation.

set.remove(element)

Parameters:

Parameter Description
element ?

Element to remove. Must be an element of the set (and hashable).

set.symmetric_difference

Returns a new mutable set containing the symmetric difference of this set with another set, sequence, or dict.

If s and t are sets, s.symmetric_difference(t) is equivalent to s ^ t; however, note that the ^ operation requires both sides to be sets, while the symmetric_difference method also accepts a sequence or a dict.

For example, 

set([1, 2]).symmetric_difference([2, 3])  # set([1, 3])

sequence set.symmetric_difference(other)

Parameters:

Parameter Description
other unknown

A set, a sequence of hashable elements, or a dict.

set.symmetric_difference_update

Returns a new mutable set containing the symmetric difference of this set with another set, sequence, or dict.

If s and t are sets, s.symmetric_difference_update(t) is equivalent to `s ^= t; however, note that the ^=` augmented assignment requires both sides to be sets, while the symmetric_difference_update method also accepts a sequence or a dict.

For example, 

s = set([1, 2])
s.symmetric_difference_update([2, 3])  # None; s == set([1, 3])

set.symmetric_difference_update(other)

Parameters:

Parameter Description
other unknown

A set, a sequence of hashable elements, or a dict.

set.union

Returns a new mutable set containing the union of this set with others.

If s and t are sets, s.union(t) is equivalent to s | t; however, note that the | operation requires both sides to be sets, while the union method also accepts sequences and dicts.

It is permissible to call union without any arguments; this returns a copy of the set.

For example, 

set([1, 2]).union([2, 3])                    # set([1, 2, 3])
set([1, 2]).union([2, 3], {3: "a", 4: "b"})  # set([1, 2, 3, 4])

sequence set.union(others)

Parameters:

Parameter Description
others list

Sets, sequences of hashable elements, or dicts.

set.update

Adds the elements found in others to this set.

For example, 

s = set()
s.update([1, 2])          # None; s is set([1, 2])
s.update([2, 3], [3, 4])  # None; s is set([1, 2, 3, 4])

If s and t are sets, s.update(t) is equivalent to s |= t; however, note that the |= augmented assignment requires both sides to be sets, while the update method also accepts sequences and dicts.

It is permissible to call update without any arguments; this leaves the set unchanged.

set.update(others)

Parameters:

Parameter Description
others list

Sets, sequences of hashable elements, or dicts.

SetReviewInput

Input for posting a review to Gerrit. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#review-input

Returned By:

Consumed By:

StarlarkDateTime

Starlark datetime object

Returned By:

StarlarkDateTime.in_epoch_seconds

Returns the time in epoch seconds for the starlark_datetime instance

long StarlarkDateTime.in_epoch_seconds()

StarlarkDateTime.strftime

Returns a string representation of the StarlarkDateTime object with your chosen formatting

string StarlarkDateTime.strftime(format)

Parameters:

Parameter Description
format string

Format string used to present StarlarkDateTime object. See https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html for patterns.

string

A language built-in type to support strings. Examples of string literals:

a = 'abc\ndef'
b = "ab'cd"
c = """multiline string"""


Strings support slicing (negative index starts from the end):


x = "hello"[2:4]  # "ll"
y = "hello"[1:-1]  # "ell"
z = "hello"[:4]  # "hell"


Slice steps can be used, too:


s = "hello"[::2] # "hlo"
t = "hello"[3:0:-1] # "lle"
Strings are not directly iterable, use the .elems() method to iterate over their characters. Examples:
"bc" in "abcd"   # evaluates to True
x = [c for c in "abc".elems()]  # x == ["a", "b", "c"]
Implicit concatenation of strings is not allowed; use the + operator instead. Comparison operators perform a lexicographical comparison; use == to test for equality.

Returned By:

Consumed By:

string.capitalize

Returns a copy of the string with its first character (if any) capitalized and the rest lowercased. This method does not support non-ascii characters.

string string.capitalize(self)

Parameters:

Parameter Description
self string

This string.

string.count

Returns the number of (non-overlapping) occurrences of substring sub in string, optionally restricting to [start:end], start being inclusive and end being exclusive.

int string.count(self, sub, start=0, end=None)

Parameters:

Parameter Description
self string

This string.
sub string

The substring to count.
start int or NoneType

Restrict to search from this position.
end int or NoneType

optional position before which to restrict to search.

string.elems

Returns an iterable value containing successive 1-element substrings of the string. Equivalent to [s[i] for i in range(len(s))], except that the returned value might not be a list.

list of string string.elems(self)

Parameters:

Parameter Description
self string

This string.

string.endswith

Returns True if the string ends with sub, otherwise False, optionally restricting to [start:end], start being inclusive and end being exclusive.

bool string.endswith(self, sub, start=0, end=None)

Parameters:

Parameter Description
self string

This string.
sub string or tuple of string

The suffix (or tuple of alternative suffixes) to match.
start int or NoneType

Test beginning at this position.
end int or NoneType

optional position at which to stop comparing.

string.find

Returns the first index where sub is found, or -1 if no such index exists, optionally restricting to [start:end], start being inclusive and end being exclusive.

int string.find(self, sub, start=0, end=None)

Parameters:

Parameter Description
self string

This string.
sub string

The substring to find.
start int or NoneType

Restrict to search from this position.
end int or NoneType

optional position before which to restrict to search.

string.format

Perform string interpolation. Format strings contain replacement fields surrounded by curly braces {}. Anything that is not contained in braces is considered literal text, which is copied unchanged to the output.If you need to include a brace character in the literal text, it can be escaped by doubling: {{ and }}A replacement field can be either a name, a number, or empty. Values are converted to strings using the str function.

# Access in order:
"{} < {}".format(4, 5) == "4 < 5"


Access by position:


"{1}, {0}".format(2, 1) == "1, 2"


Access by name:


"x{key}x".format(key = 2) == "x2x"

string string.format(self, kwargs, args)

Parameters:

Parameter Description
self string

This string.
kwargs dict

Dictionary of arguments.
args list

List of arguments.

string.index

Returns the first index where sub is found, or raises an error if no such index exists, optionally restricting to [start:end]start being inclusive and end being exclusive.

int string.index(self, sub, start=0, end=None)

Parameters:

Parameter Description
self string

This string.
sub string

The substring to find.
start int or NoneType

Restrict to search from this position.
end int or NoneType

optional position before which to restrict to search.

string.isalnum

Returns True if all characters in the string are alphanumeric ([a-zA-Z0-9]) and there is at least one character.

bool string.isalnum(self)

Parameters:

Parameter Description
self string

This string.

string.isalpha

Returns True if all characters in the string are alphabetic ([a-zA-Z]) and there is at least one character.

bool string.isalpha(self)

Parameters:

Parameter Description
self string

This string.

string.isdigit

Returns True if all characters in the string are digits ([0-9]) and there is at least one character.

bool string.isdigit(self)

Parameters:

Parameter Description
self string

This string.

string.islower

Returns True if all cased characters in the string are lowercase and there is at least one character.

bool string.islower(self)

Parameters:

Parameter Description
self string

This string.

string.isspace

Returns True if all characters are white space characters and the string contains at least one character.

bool string.isspace(self)

Parameters:

Parameter Description
self string

This string.

string.istitle

Returns True if the string is in title case and it contains at least one character. This means that every uppercase character must follow an uncased one (e.g. whitespace) and every lowercase character must follow a cased one (e.g. uppercase or lowercase).

bool string.istitle(self)

Parameters:

Parameter Description
self string

This string.

string.isupper

Returns True if all cased characters in the string are uppercase and there is at least one character.

bool string.isupper(self)

Parameters:

Parameter Description
self string

This string.

string.join

Returns a string in which the string elements of the argument have been joined by this string as a separator. Example:

"|".join(["a", "b", "c"]) == "a|b|c"

string string.join(self, elements)

Parameters:

Parameter Description
self string
elements unknown

The objects to join.

string.lower

Returns the lower case version of this string.

string string.lower(self)

Parameters:

Parameter Description
self string

string.lstrip

Returns a copy of the string where leading characters that appear in chars are removed. Note that chars is not a prefix: all combinations of its value are removed:

"abcba".lstrip("ba") == "cba"

string string.lstrip(self, chars=None)

Parameters:

Parameter Description
self string
chars string or NoneType

The characters to remove, or all whitespace if None.

string.partition

Splits the input string at the first occurrence of the separator sep and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, partition returns (self, '', '').

tuple string.partition(self, sep)

Parameters:

Parameter Description
self string
sep string

The string to split on.

string.removeprefix

If the string starts with prefix, returns a new string with the prefix removed. Otherwise, returns the string.

string string.removeprefix(self, prefix)

Parameters:

Parameter Description
self string

This string.
prefix string

The prefix to remove if present.

string.removesuffix

If the string ends with suffix, returns a new string with the suffix removed. Otherwise, returns the string.

string string.removesuffix(self, suffix)

Parameters:

Parameter Description
self string

This string.
suffix string

The suffix to remove if present.

string.replace

Returns a copy of the string in which the occurrences of old have been replaced with new, optionally restricting the number of replacements to count.

string string.replace(self, old, new, count=-1)

Parameters:

Parameter Description
self string

This string.
old string

The string to be replaced.
new string

The string to replace with.
count int

The maximum number of replacements. If omitted, or if the value is negative, there is no limit.

string.rfind

Returns the last index where sub is found, or -1 if no such index exists, optionally restricting to [start:end], start being inclusive and end being exclusive.

int string.rfind(self, sub, start=0, end=None)

Parameters:

Parameter Description
self string

This string.
sub string

The substring to find.
start int or NoneType

Restrict to search from this position.
end int or NoneType

optional position before which to restrict to search.

string.rindex

Returns the last index where sub is found, or raises an error if no such index exists, optionally restricting to [start:end], start being inclusive and end being exclusive.

int string.rindex(self, sub, start=0, end=None)

Parameters:

Parameter Description
self string

This string.
sub string

The substring to find.
start int or NoneType

Restrict to search from this position.
end int or NoneType

optional position before which to restrict to search.

string.rpartition

Splits the input string at the last occurrence of the separator sep and returns the resulting partition as a three-element tuple of the form (before, separator, after). If the input string does not contain the separator, rpartition returns ('', '', self).

tuple string.rpartition(self, sep)

Parameters:

Parameter Description
self string
sep string

The string to split on.

string.rsplit

Returns a list of all the words in the string, using sep as the separator, optionally limiting the number of splits to maxsplit. Except for splitting from the right, this method behaves like split().

list of string string.rsplit(self, sep, maxsplit=None)

Parameters:

Parameter Description
self string

This string.
sep string

The string to split on.
maxsplit int or NoneType

The maximum number of splits.

string.rstrip

Returns a copy of the string where trailing characters that appear in chars are removed. Note that chars is not a suffix: all combinations of its value are removed:

"abcbaa".rstrip("ab") == "abc"

string string.rstrip(self, chars=None)

Parameters:

Parameter Description
self string

This string.
chars string or NoneType

The characters to remove, or all whitespace if None.

string.split

Returns a list of all the words in the string, using sep as the separator, optionally limiting the number of splits to maxsplit.

list of string string.split(self, sep, maxsplit=None)

Parameters:

Parameter Description
self string

This string.
sep string

The string to split on.
maxsplit int or NoneType

The maximum number of splits.

string.splitlines

Splits the string at line boundaries ('\n', '\r\n', '\r') and returns the result as a new mutable list.

list of string string.splitlines(self, keepends=False)

Parameters:

Parameter Description
self string

This string.
keepends bool

Whether the line breaks should be included in the resulting list.

string.startswith

Returns True if the string starts with sub, otherwise False, optionally restricting to [start:end], start being inclusive and end being exclusive.

bool string.startswith(self, sub, start=0, end=None)

Parameters:

Parameter Description
self string

This string.
sub string or tuple of string

The prefix (or tuple of alternative prefixes) to match.
start int or NoneType

Test beginning at this position.
end int or NoneType

Stop comparing at this position.

string.strip

Returns a copy of the string where leading or trailing characters that appear in chars are removed. Note that chars is neither a prefix nor a suffix: all combinations of its value are removed:

"aabcbcbaa".strip("ab") == "cbc"

string string.strip(self, chars=None)

Parameters:

Parameter Description
self string

This string.
chars string or NoneType

The characters to remove, or all whitespace if None.

string.title

Converts the input string into title case, i.e. every word starts with an uppercase letter while the remaining letters are lowercase. In this context, a word means strictly a sequence of letters. This method does not support supplementary Unicode characters.

string string.title(self)

Parameters:

Parameter Description
self string

This string.

string.upper

Returns the upper case version of this string.

string string.upper(self)

Parameters:

Parameter Description
self string

struct

Immutable struct type.

struct

Creates a new immutable struct. Structs with the same keys/values are equal. The struct's keys and values are passed in as keyword arguments.

StructImpl struct(kwargs)

Parameters:

Parameter Description
kwargs dict

Dictionary of Args.

Example:

Create a struct:

Structs are immutable objects to group values.

my_struct = struct(foo='bar')
x = my_struct.foo

time_delta

A time delta.

time_delta.total_seconds

Total number of seconds in a timedelta object.

long time_delta.total_seconds()

toml

Module for parsing TOML in Copybara.

toml.parse

Parse the TOML content. Returns a toml object.

TomlContent toml.parse(content)

Parameters:

Parameter Description
content string

TOML content to be parsed

Example:

Parsing a TOML string:

To parse a TOML string, pass the string into the parser.

toml.parse("foo = 42")

TomlContent

Object containing parsed TOML values.

Returned By:

TomlContent.get

Retrieve the value from the parsed TOML for the given key. If the key is not defined, this will return None.

unknown TomlContent.get(key)

Parameters:

Parameter Description
key string

The dotted key expression

Example:

Get the value for a key:

Pass in the name of the key. This will return the value.

TomlContent.get("foo")

TomlContent.get_or_default

Retrieve the value from the parsed TOML for the given key. If the key is not defined, this will return the default value.

unknown TomlContent.get_or_default(key, default)

Parameters:

Parameter Description
key string

The dotted key expression
default unknown

The default value to return if the key isn't found.

Example:

Get the value for a key, with a default value:

Pass in the name of the key. This will return the value.

TomlContent.get_or_default("foo", "bar")

transformation

A single operation which modifies the source checked out from the origin, prior to writing it to the destination. Transformations can also be used to perform validations or checks.

Many common transformations are provided by the built-in libraries, such as core.

Custom transformations can be defined in Starlark code via core.dynamic_transform.

Returned By:

Consumed By:

transformation_status

The status of a Transformation that was just run. Either a 'success' or a 'no-op'.

Fields:

Name Description
is_noop bool

Whether this status has the value NO-OP.
is_success bool

Whether this status has the value SUCCESS.

Returned By:

TransformWork

Data about the set of changes that are being migrated. It includes information about changes like: the author to be used for commit, change message, etc. You receive a TransformWork object as an argument when defining a dynamic transform.

Fields:

Name Description
author author

Author to be used in the change
changes Changes

List of changes that will be migrated
console Console

Get an instance of the console to report errors or warnings
message string

Message to be used in the change
params dict

Parameters for the function if created with core.dynamic_transform

Consumed By:

ctx.add_label

Add a label to the end of the description

ctx.add_label(label, value, separator="=", hidden=False)

Parameters:

Parameter Description
label string

The label to add
value string

The new value for the label
separator string

The separator to use for the label
hidden bool

Don't show the label in the message but only keep it internally

ctx.add_or_replace_label

Replace an existing label or add it to the end of the description

ctx.add_or_replace_label(label, value, separator="=")

Parameters:

Parameter Description
label string

The label to add/replace
value string

The new value for the label
separator string

The separator to use for the label

ctx.add_text_before_labels

Add a text to the description before the labels paragraph

ctx.add_text_before_labels(text)

Parameters:

Parameter Description
text string

ctx.create_symlink

Create a symlink

ctx.create_symlink(link, target)

Parameters:

Parameter Description
link Path

The link path
target Path

The target path

ctx.destination_api

Returns an api handle for the destination repository. Methods available depend on the destination type. Use with extreme caution, as external calls can make workflow non-deterministic and possibly irreversible. Can have side effects in dry-runmode.

endpoint ctx.destination_api()

ctx.destination_info

Returns an object to store additional configuration and data for the destination. An object is only returned if supported by the destination.

DestinationInfo ctx.destination_info()

ctx.destination_reader

Returns a handle to read files from the destination, if supported by the destination.

destination_reader ctx.destination_reader()

ctx.fill_template

Replaces variables in templates with the values from this revision.

string ctx.fill_template(template)

Parameters:

Parameter Description
template string

The template to use

Example:

Use the SHA1 in a string:

Create a custom transformation which is successful.

filled_template = ctx.fill_template('Current Revision: ${GIT_SHORT_SHA1}')

filled_template will contain (for example) 'Current Revision: abcdef12'

ctx.find_all_labels

Tries to find all the values for a label. First it looks at the generated message (that is, labels that might have been added by previous transformations), then it looks in all the commit messages being imported and finally in the resolved reference passed in the CLI.

list of string ctx.find_all_labels(label)

Parameters:

Parameter Description
label string

The label to find

ctx.find_label

Tries to find a label. First it looks at the generated message (that is, labels that might have been added by previous transformations), then it looks in all the commit messages being imported and finally in the resolved reference passed in the CLI. Returns the first such label value found this way.

string ctx.find_label(label)

Parameters:

Parameter Description
label string

The label to find

ctx.list

List files in the checkout/work directory that matches a glob

list of Path ctx.list(paths)

Parameters:

Parameter Description
paths glob

A glob representing the paths to list

ctx.new_path

Create a new path

Path ctx.new_path(path)

Parameters:

Parameter Description
path string

The string representing the path, relative to the checkout root directory

ctx.noop

The status returned by a no-op Transformation

transformation_status ctx.noop(message)

Parameters:

Parameter Description
message string

Example:

Define a dynamic transformation:

Create a custom transformation which fails.

def my_transform(ctx):
  # do some stuff
  return ctx.noop('Error! The transform didn\'t do anything.')

ctx.now_as_string

Get current date as a string

string ctx.now_as_string(format="yyyy-MM-dd", zone="UTC")

Parameters:

Parameter Description
format string

The format to use. See: https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html for details.
zone string

The timezone id to use. See https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html. By default UTC

ctx.origin_api

Returns an api handle for the origin repository. Methods available depend on the origin type. Use with extreme caution, as external calls can make workflow non-deterministic and possibly irreversible. Can have side effects in dry-runmode.

endpoint ctx.origin_api()

ctx.read_path

Read the content of path as UTF-8

string ctx.read_path(path)

Parameters:

Parameter Description
path Path

The Path to read from

ctx.remove_label

Remove a label from the message if present

ctx.remove_label(label, whole_message=False)

Parameters:

Parameter Description
label string

The label to delete
whole_message bool

By default Copybara only looks in the last paragraph for labels. This flagmake it replace labels in the whole message.

ctx.replace_label

Replace a label if it exist in the message

ctx.replace_label(label, value, separator="=", whole_message=False)

Parameters:

Parameter Description
label string

The label to replace
value string

The new value for the label
separator string

The separator to use for the label
whole_message bool

By default Copybara only looks in the last paragraph for labels. This flagmake it replace labels in the whole message.

ctx.run

Run a glob or a transform. For example:
files = ctx.run(glob(['**.java']))
or
ctx.run(core.move("foo", "bar"))
or

unknown ctx.run(runnable)

Parameters:

Parameter Description
runnable glob or transformation

When runnable is a glob, returns a list of files in the workdir which it matches.

When runnable is a transformation, runs it in the workdir.

ctx.set_author

Update the author to be used in the change

ctx.set_author(author)

Parameters:

Parameter Description
author author

ctx.set_executable

Set the executable permission of a file

ctx.set_executable(path, value)

Parameters:

Parameter Description
path Path

The Path to set the executable permission of
value bool

Whether or not the file should be executable

ctx.set_message

Update the message to be used in the change

ctx.set_message(message)

Parameters:

Parameter Description
message string

ctx.success

The status returned by a successful Transformation

transformation_status ctx.success()

Example:

Define a dynamic transformation:

Create a custom transformation which is successful.

def my_transform(ctx):
  # do some stuff
  return ctx.success()

For compatibility reasons, returning nothing is the same as returning success.

ctx.write_path

Write an arbitrary string to a path (UTF-8 will be used)

ctx.write_path(path, content)

Parameters:

Parameter Description
path Path

The Path to write to
content string

The content of the file

tuple

The built-in tuple type. Example tuple expressions:

x = (1, 2, 3)
Accessing elements is possible using indexing (starts from 0):
e = x[1]   # e == 2
Lists support the + operator to concatenate two tuples. Example:
x = (1, 2) + (3, 4)   # x == (1, 2, 3, 4)
x = ("a", "b")
x += ("c",)            # x == ("a", "b", "c")
Similar to lists, tuples support slice operations:
('a', 'b', 'c', 'd')[1:3]   # ('b', 'c')
('a', 'b', 'c', 'd')[::2]  # ('a', 'c')
('a', 'b', 'c', 'd')[3:0:-1]  # ('d', 'c', 'b')
Tuples are immutable, therefore x[1] = "a" is not supported.

Returned By:

VersionSelector

Select a version from a list of versions

Returned By:

Consumed By:

xml

Set of functions to work with XML in Copybara.

xml.xpath

Run an xpath expression

unknown xml.xpath(content, expression, type)

Parameters:

Parameter Description
content string

The XML content
expression string

XPath expression
type string

The type of the return value, see http://www.w3.org/TR/xpathfor more details. For now we support STRING, BOOLEAN & NUMBER.

copybara_flags

All flag options available to the Copybara CLI.

Command line flags:

Name Type Description
--allow-empty-diff boolean If set to false, Copybara will not write to the destination if the exact same change is already pending in the destination. Currently only supported for git.github_pr_destination and git.gerrit_destination.
--allowed-git-push-options list This is a flag used to allowlist push options sent to git servers. E.g. copybara copy.bara.sky --git-push-option="foo,bar" would make copybara validate push so that the only push options (if there are any) used are 'foo' and 'bar'. If this flag is unset, it will skip push options validation. Set to "" to allow no push options.
--commands-timeout duration Commands timeout. Example values: 30s, 20m, 1h, etc.
--config-root string Configuration root path to be used for resolving absolute config labels like '//foo/bar'
--console-file-flush-interval duration How often Copybara should flush the console to the output file. (10s, 1m, etc.)If set to 0s, console will be flushed only at the end. Example values: 30s, 20m, 1h, etc.
--console-file-path string If set, write the console output also to the given file path.
--debug-file-break string Stop when file matching the glob changes
--debug-metadata-break boolean Stop when message and/or author changes
--debug-transform-break string Stop when transform description matches
--diff-bin string Command line diff tool bin used in merge import. Defaults to diff3, but users can pass in their own diffing tools (along with requisite arg reordering)
--disable-reversible-check boolean If set, all workflows will be executed without reversible_check, overriding the workflow config and the normal behavior for CHANGE_REQUEST mode.
--dry-run boolean Run the migration in dry-run mode. Some destination implementations might have some side effects (like creating a code review), but never submit to a main branch.
--event-monitor list Eventmonitors to enable. These must be in the list of available monitors.
--experiment-checkout-affected-files boolean If set, copybara will only checkout affected files at git origin. Note that this is experimental.
--force, --force-update boolean Force the migration even if Copybara cannot find in the destination a change that is an ancestor of the one(s) being migrated. This should be used with care, as it could lose changes when migrating a previous/conflicting change.
--git-credential-helper-store-file string Credentials store file to be used. See https://git-scm.com/docs/git-credential-store
--git-no-verify boolean Pass the '--no-verify' option to git pushes and commits to disable git commit hooks.
--git-origin-fetch-depth integer Use a shallow clone of the specified depth for git.origin. If set, only the n most recent changes' tree states are imported with older changes omitted.
--git-push-option list This is a repeatable flag used to set git push level flags to send to git servers. E.g. copybara copy.bara.sky --git-push-option foo --git-push-option bar would make git operations done by copybara under the hood use the --push-option flags: git push -push-option=foo -push-option=bar ...
--git-tag-overwrite boolean If set, copybara will force update existing git tag
--info-list-only boolean When set, the INFO command will print a list of workflows defined in the file.
--labels immutableMap Additional flags. Can be accessed in feedback and mirror context objects via the cli_labels field. In core.workflow, they are accessible as labels, but with names uppercased and prefixed with FLAG_ to avoid name clashes with existing labels. I.e. --labels=label1:value1 will define a label FLAG_LABEL1Format: --labels=flag1:value1,flag2:value2 Or: --labels flag1:value1,flag2:value2
--noansi boolean Don't use ANSI output for messages
--nocleanup boolean Cleanup the output directories. This includes the workdir, scratch clones of Git repos, etc. By default is set to false and directories will be cleaned prior to the execution. If set to true, the previous run output will not be cleaned up. Keep in mind that running in this mode will lead to an ever increasing disk usage.
--nogit-credential-helper-store boolean Disable using credentials store. See https://git-scm.com/docs/git-credential-store
--nogit-prompt boolean Disable username/password prompt and fail if no credentials are found. This flag sets the environment variable GIT_TERMINAL_PROMPT which is intended for automated jobs running Git https://git-scm.com/docs/git/2.3.0#git-emGITTERMINALPROMPTem
--noprompt boolean Don't prompt, this will answer all prompts with 'yes'
--output-limit int Limit the output in the console to a number of records. Each subcommand might use this flag differently. Defaults to 0, which shows all the output.
--output-root string The root directory where to generate output files. If not set, ~/copybara/out is used by default. Use with care, Copybara might remove files inside this root if necessary.
--patch-bin string Path for GNU Patch command
--remote-http-files-connection-timeout duration Timeout for the fetch operation, e.g. 30s. Example values: 30s, 20m, 1h, etc.
--repo-timeout duration Repository operation timeout duration. Example values: 30s, 20m, 1h, etc.
--squash boolean Override workflow's mode with 'SQUASH'. This is useful mainly for workflows that use 'ITERATIVE' mode, when we want to run a single export with 'SQUASH', maybe to fix an issue. Always use --dry-run before, to test your changes locally.
--validate-starlark string Starlark should be validated prior to execution, but this might break legacy configs. Options are LOOSE, STRICT
--version-selector-use-cli-ref boolean If command line ref is to used with a version selector, pass this flag to tell copybara to use it.
-v, --verbose boolean Verbose output.