## Table of Contents
- [archive](#archive)
- [archive.extract](#archiveextract)
- [author](#author)
- [authoring](#authoring)
- [authoring.allowed](#authoringallowed)
- [authoring.overwrite](#authoringoverwrite)
- [authoring.pass_thru](#authoringpass_thru)
- [authoring_class](#authoring_class)
- [buildozer](#buildozer)
- [buildozer.cmd](#buildozercmd)
- [buildozer.create](#buildozercreate)
- [buildozer.delete](#buildozerdelete)
- [buildozer.modify](#buildozermodify)
- [buildozer.print](#buildozerprint)
- [change](#change)
- [ChangeMessage](#changemessage)
- [message.label_values](#messagelabel_values)
- [Changes](#changes)
- [checker](#checker)
- [Command](#command)
- [Console](#console)
- [console.error](#consoleerror)
- [console.info](#consoleinfo)
- [console.progress](#consoleprogress)
- [console.verbose](#consoleverbose)
- [console.warn](#consolewarn)
- [core](#core)
- [core.action](#coreaction)
- [core.action_migration](#coreaction_migration)
- [core.autopatch_config](#coreautopatch_config)
- [core.convert_encoding](#coreconvert_encoding)
- [core.copy](#corecopy)
- [core.dynamic_feedback](#coredynamic_feedback)
- [core.dynamic_transform](#coredynamic_transform)
- [core.fail_with_noop](#corefail_with_noop)
- [core.feedback](#corefeedback)
- [core.filter_replace](#corefilter_replace)
- [core.format](#coreformat)
- [core.latest_version](#corelatest_version)
- [core.merge_import_config](#coremerge_import_config)
- [core.move](#coremove)
- [core.remove](#coreremove)
- [core.rename](#corerename)
- [core.replace](#corereplace)
- [core.replace_mapper](#corereplace_mapper)
- [core.reverse](#corereverse)
- [core.todo_replace](#coretodo_replace)
- [core.transform](#coretransform)
- [core.verify_match](#coreverify_match)
- [core.workflow](#coreworkflow)
- [core.autopatch_config](#coreautopatch_config)
- [datetime](#datetime)
- [datetime.fromtimestamp](#datetimefromtimestamp)
- [datetime.now](#datetimenow)
- [description_checker](#description_checker)
- [destination](#destination)
- [destination_effect](#destination_effect)
- [destination_reader](#destination_reader)
- [destination_reader.copy_destination_files](#destination_readercopy_destination_files)
- [destination_reader.file_exists](#destination_readerfile_exists)
- [destination_reader.read_file](#destination_readerread_file)
- [destination_ref](#destination_ref)
- [endpoint](#endpoint)
- [endpoint.new_destination_ref](#endpointnew_destination_ref)
- [endpoint.new_origin_ref](#endpointnew_origin_ref)
- [feedback.context](#feedbackcontext)
- [feedback.context.error](#feedbackcontexterror)
- [feedback.context.noop](#feedbackcontextnoop)
- [feedback.context.record_effect](#feedbackcontextrecord_effect)
- [feedback.context.success](#feedbackcontextsuccess)
- [feedback.finish_hook_context](#feedbackfinish_hook_context)
- [feedback.finish_hook_context.error](#feedbackfinish_hook_contexterror)
- [feedback.finish_hook_context.noop](#feedbackfinish_hook_contextnoop)
- [feedback.finish_hook_context.record_effect](#feedbackfinish_hook_contextrecord_effect)
- [feedback.finish_hook_context.success](#feedbackfinish_hook_contextsuccess)
- [feedback.revision_context](#feedbackrevision_context)
- [feedback.revision_context.fill_template](#feedbackrevision_contextfill_template)
- [filter_replace](#filter_replace)
- [folder](#folder)
- [folder.destination](#folderdestination)
- [folder.origin](#folderorigin)
- [format](#format)
- [format.buildifier](#formatbuildifier)
- [gerrit_api_obj](#gerrit_api_obj)
- [gerrit_api_obj.abandon_change](#gerrit_api_objabandon_change)
- [gerrit_api_obj.delete_vote](#gerrit_api_objdelete_vote)
- [gerrit_api_obj.get_actions](#gerrit_api_objget_actions)
- [gerrit_api_obj.get_change](#gerrit_api_objget_change)
- [gerrit_api_obj.list_changes](#gerrit_api_objlist_changes)
- [gerrit_api_obj.new_destination_ref](#gerrit_api_objnew_destination_ref)
- [gerrit_api_obj.new_origin_ref](#gerrit_api_objnew_origin_ref)
- [gerrit_api_obj.post_review](#gerrit_api_objpost_review)
- [gerrit_api_obj.submit_change](#gerrit_api_objsubmit_change)
- [gerritapi.AccountInfo](#gerritapiaccountinfo)
- [gerritapi.ApprovalInfo](#gerritapiapprovalinfo)
- [gerritapi.ChangeInfo](#gerritapichangeinfo)
- [gerritapi.ChangeMessageInfo](#gerritapichangemessageinfo)
- [gerritapi.ChangesQuery](#gerritapichangesquery)
- [gerritapi.CommitInfo](#gerritapicommitinfo)
- [gerritapi.getActionInfo](#gerritapigetactioninfo)
- [gerritapi.GitPersonInfo](#gerritapigitpersoninfo)
- [gerritapi.LabelInfo](#gerritapilabelinfo)
- [gerritapi.ParentCommitInfo](#gerritapiparentcommitinfo)
- [gerritapi.ReviewResult](#gerritapireviewresult)
- [gerritapi.RevisionInfo](#gerritapirevisioninfo)
- [gerritapi.SubmitRequirementExpressionInfo](#gerritapisubmitrequirementexpressioninfo)
- [git](#git)
- [git.destination](#gitdestination)
- [git.gerrit_api](#gitgerrit_api)
- [git.gerrit_destination](#gitgerrit_destination)
- [git.gerrit_origin](#gitgerrit_origin)
- [git.gerrit_trigger](#gitgerrit_trigger)
- [git.github_api](#gitgithub_api)
- [git.github_destination](#gitgithub_destination)
- [git.github_origin](#gitgithub_origin)
- [git.github_pr_destination](#gitgithub_pr_destination)
- [git.github_pr_origin](#gitgithub_pr_origin)
- [git.github_trigger](#gitgithub_trigger)
- [git.integrate](#gitintegrate)
- [git.latest_version](#gitlatest_version)
- [git.mirror](#gitmirror)
- [git.origin](#gitorigin)
- [git.review_input](#gitreview_input)
- [git.mirrorContext](#gitmirrorcontext)
- [git.mirrorContext.cherry_pick](#gitmirrorcontextcherry_pick)
- [git.mirrorContext.create_branch](#gitmirrorcontextcreate_branch)
- [git.mirrorContext.destination_fetch](#gitmirrorcontextdestination_fetch)
- [git.mirrorContext.destination_push](#gitmirrorcontextdestination_push)
- [git.mirrorContext.error](#gitmirrorcontexterror)
- [git.mirrorContext.merge](#gitmirrorcontextmerge)
- [git.mirrorContext.noop](#gitmirrorcontextnoop)
- [git.mirrorContext.origin_fetch](#gitmirrorcontextorigin_fetch)
- [git.mirrorContext.rebase](#gitmirrorcontextrebase)
- [git.mirrorContext.record_effect](#gitmirrorcontextrecord_effect)
- [git.mirrorContext.references](#gitmirrorcontextreferences)
- [git.mirrorContext.success](#gitmirrorcontextsuccess)
- [git_merge_result](#git_merge_result)
- [github_api_combined_status_obj](#github_api_combined_status_obj)
- [github_api_commit_author_obj](#github_api_commit_author_obj)
- [github_api_commit_obj](#github_api_commit_obj)
- [github_api_github_commit_obj](#github_api_github_commit_obj)
- [github_api_issue_comment_obj](#github_api_issue_comment_obj)
- [github_api_obj](#github_api_obj)
- [github_api_obj.add_label](#github_api_objadd_label)
- [github_api_obj.create_issue](#github_api_objcreate_issue)
- [github_api_obj.create_release](#github_api_objcreate_release)
- [github_api_obj.create_status](#github_api_objcreate_status)
- [github_api_obj.delete_reference](#github_api_objdelete_reference)
- [github_api_obj.get_authenticated_user](#github_api_objget_authenticated_user)
- [github_api_obj.get_check_runs](#github_api_objget_check_runs)
- [github_api_obj.get_combined_status](#github_api_objget_combined_status)
- [github_api_obj.get_commit](#github_api_objget_commit)
- [github_api_obj.get_pull_request_comment](#github_api_objget_pull_request_comment)
- [github_api_obj.get_pull_request_comments](#github_api_objget_pull_request_comments)
- [github_api_obj.get_pull_requests](#github_api_objget_pull_requests)
- [github_api_obj.get_reference](#github_api_objget_reference)
- [github_api_obj.get_references](#github_api_objget_references)
- [github_api_obj.list_issue_comments](#github_api_objlist_issue_comments)
- [github_api_obj.new_destination_ref](#github_api_objnew_destination_ref)
- [github_api_obj.new_origin_ref](#github_api_objnew_origin_ref)
- [github_api_obj.new_release_request](#github_api_objnew_release_request)
- [github_api_obj.post_issue_comment](#github_api_objpost_issue_comment)
- [github_api_obj.update_pull_request](#github_api_objupdate_pull_request)
- [github_api_obj.update_reference](#github_api_objupdate_reference)
- [github_api_pull_request_comment_obj](#github_api_pull_request_comment_obj)
- [github_api_pull_request_obj](#github_api_pull_request_obj)
- [github_api_ref_obj](#github_api_ref_obj)
- [github_api_revision_obj](#github_api_revision_obj)
- [github_api_status_obj](#github_api_status_obj)
- [github_api_user_obj](#github_api_user_obj)
- [github_app_obj](#github_app_obj)
- [github_check_run_obj](#github_check_run_obj)
- [github_check_runs_obj](#github_check_runs_obj)
- [github_check_suite_obj](#github_check_suite_obj)
- [github_check_suites_response_obj](#github_check_suites_response_obj)
- [github_create_release_obj](#github_create_release_obj)
- [github_create_release_obj.set_draft](#github_create_release_objset_draft)
- [github_create_release_obj.set_generate_release_notes](#github_create_release_objset_generate_release_notes)
- [github_create_release_obj.set_latest](#github_create_release_objset_latest)
- [github_create_release_obj.set_prerelease](#github_create_release_objset_prerelease)
- [github_create_release_obj.with_body](#github_create_release_objwith_body)
- [github_create_release_obj.with_commitish](#github_create_release_objwith_commitish)
- [github_create_release_obj.with_name](#github_create_release_objwith_name)
- [github_release_obj](#github_release_obj)
- [glob](#glob)
- [Globals](#globals)
- [glob](#glob)
- [new_author](#new_author)
- [parse_message](#parse_message)
- [go](#go)
- [go.go_proxy_resolver](#gogo_proxy_resolver)
- [go.go_proxy_version_list](#gogo_proxy_version_list)
- [hg](#hg)
- [hg.origin](#hgorigin)
- [html](#html)
- [html.xpath](#htmlxpath)
- [Issue](#issue)
- [mapping_function](#mapping_function)
- [metadata](#metadata)
- [metadata.add_header](#metadataadd_header)
- [metadata.expose_label](#metadataexpose_label)
- [metadata.map_author](#metadatamap_author)
- [metadata.map_references](#metadatamap_references)
- [metadata.remove_label](#metadataremove_label)
- [metadata.replace_message](#metadatareplace_message)
- [metadata.restore_author](#metadatarestore_author)
- [metadata.save_author](#metadatasave_author)
- [metadata.scrubber](#metadatascrubber)
- [metadata.squash_notes](#metadatasquash_notes)
- [metadata.use_last_change](#metadatause_last_change)
- [metadata.verify_match](#metadataverify_match)
- [origin](#origin)
- [origin_ref](#origin_ref)
- [output_obj](#output_obj)
- [patch](#patch)
- [patch.apply](#patchapply)
- [patch.quilt_apply](#patchquilt_apply)
- [Path](#path)
- [path.exists](#pathexists)
- [path.read_symlink](#pathread_symlink)
- [path.relativize](#pathrelativize)
- [path.remove](#pathremove)
- [path.resolve](#pathresolve)
- [path.resolve_sibling](#pathresolve_sibling)
- [path.rmdir](#pathrmdir)
- [PathAttributes](#pathattributes)
- [re2](#re2)
- [re2.compile](#re2compile)
- [re2.quote](#re2quote)
- [re2_matcher](#re2_matcher)
- [re2_matcher.end](#re2_matcherend)
- [re2_matcher.find](#re2_matcherfind)
- [re2_matcher.group](#re2_matchergroup)
- [re2_matcher.group_count](#re2_matchergroup_count)
- [re2_matcher.matches](#re2_matchermatches)
- [re2_matcher.replace_all](#re2_matcherreplace_all)
- [re2_matcher.replace_first](#re2_matcherreplace_first)
- [re2_matcher.start](#re2_matcherstart)
- [re2_pattern](#re2_pattern)
- [re2_pattern.matcher](#re2_patternmatcher)
- [re2_pattern.matches](#re2_patternmatches)
- [remotefiles](#remotefiles)
- [remotefiles.github_archive](#remotefilesgithub_archive)
- [remotefiles.origin](#remotefilesorigin)
- [rust_version_requirement](#rust_version_requirement)
- [rust_version_requirement.fulfills](#rust_version_requirementfulfills)
- [SetReviewInput](#setreviewinput)
- [StarlarkDateTime](#starlarkdatetime)
- [StarlarkDateTime.in_epoch_seconds](#starlarkdatetimein_epoch_seconds)
- [StarlarkDateTime.strftime](#starlarkdatetimestrftime)
- [struct](#struct)
- [struct](#struct)
- [toml](#toml)
- [toml.parse](#tomlparse)
- [TomlContent](#tomlcontent)
- [TomlContent.get](#tomlcontentget)
- [TomlContent.get_or_default](#tomlcontentget_or_default)
- [transformation](#transformation)
- [transformation_status](#transformation_status)
- [TransformWork](#transformwork)
- [ctx.add_label](#ctxadd_label)
- [ctx.add_or_replace_label](#ctxadd_or_replace_label)
- [ctx.add_text_before_labels](#ctxadd_text_before_labels)
- [ctx.create_symlink](#ctxcreate_symlink)
- [ctx.destination_api](#ctxdestination_api)
- [ctx.destination_info](#ctxdestination_info)
- [ctx.destination_reader](#ctxdestination_reader)
- [ctx.fill_template](#ctxfill_template)
- [ctx.find_all_labels](#ctxfind_all_labels)
- [ctx.find_label](#ctxfind_label)
- [ctx.list](#ctxlist)
- [ctx.new_path](#ctxnew_path)
- [ctx.noop](#ctxnoop)
- [ctx.now_as_string](#ctxnow_as_string)
- [ctx.origin_api](#ctxorigin_api)
- [ctx.read_path](#ctxread_path)
- [ctx.remove_label](#ctxremove_label)
- [ctx.replace_label](#ctxreplace_label)
- [ctx.run](#ctxrun)
- [ctx.set_author](#ctxset_author)
- [ctx.set_executable](#ctxset_executable)
- [ctx.set_message](#ctxset_message)
- [ctx.success](#ctxsuccess)
- [ctx.write_path](#ctxwrite_path)
- [VersionSelector](#versionselector)
- [xml](#xml)
- [xml.xpath](#xmlxpath)
- [copybara_flags](#copybara_flags)
## archive
Functions to work with archives.
archive.extract(archive, type="AUTO", destination_folder=None, paths=None)
Path
The path to the archive file.
type |string
The archive type. Supported types: AUTO, JAR, ZIP, TAR, and TAR_GZ. 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 changestring
The email of the author
name |string
The name of the author
authoring_class
authoring.allowed(default, allowlist)
string
The default author for commits in the destination. This is used in squash mode workflows or when users are not on the list.
|sequence of string
List of authors in the origin that are allowed to contribute code. The authors must be unique
authoring_class
authoring.overwrite(default)
string
The default author for commits in the destination
authoring_class
authoring.pass_thru(default)
string
The default author for commits in the destination. This is used in squash mode workflows or if author cannot be determined.
Command
buildozer.cmd(forward, reverse=None)
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:
transformation
buildozer.create(target, rule_type, commands=[], before='', after='')
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='')
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)
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.
string
buildozer.print(ctx, attr, target)
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 labelsauthor
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, sequence 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.string
First line of this message
text |string
The text description this message, not including the labels.
sequence of string
message.label_values(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 transformationssequence of change
List of changes that will be migrated
migrated |sequence 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 filesconsole.error(message)
string
message to log
### console.info Show an info message in the consoleconsole.info(message)
string
message to log
### console.progress Show a progress message in the consoleconsole.progress(message)
string
message to log
### console.verbose Show an info message in the console if verbose logging is enabled.console.verbose(message)
string
message to log
### console.warn Show a warning in the consoleconsole.warn(message)
string
message to log
## core Core functionality for creating migrations, and basic transformations.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. `--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={})
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:core.action_migration(name, origin, endpoints, action, description=None, filesystem=False)
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:
```
endpoint = struct(
some_endpoint = foo.foo_api(...configuration...),
other_endpoint = baz.baz_api(...configuration...),
)
```
Then they will be accessible in the action as `ctx.endpoints.some_endpoint` and `ctx.endpoints.other_endpoint`
unknown
The action to execute when the migration is triggered.
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 generationcore.autopatch_config
core.autopatch_config(header=None, suffix='.patch', directory_prefix='None', directory='AUTOPATCHES', strip_file_names_and_line_numbers=False, paths=None)
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/PATCHES/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
paths |glob
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 filestransformation
core.convert_encoding(before, after, paths)
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
transformation
core.copy(before, after, paths=glob(["**"]), overwrite=False, regex_groups={})
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 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](https://github.com/google/re2/wiki/Syntax) syntax. For example {"x": "[A-Za-z]+"}
dynamic.action
core.dynamic_feedback(impl, params={})
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 developerstransformation
core.dynamic_transform(impl, params={})
callable
The Skylark function to call
params |dict
The parameters to the function. Will be available under ctx.params
dynamic.action
core.fail_with_noop(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:core.feedback(name, origin, destination, actions=[], action=None, description=None)
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.
actions |sequence
DEPRECATED: **DO NOT USE**
A list of feedback actions to perform, with the following semantics:
- There is no guarantee of the order of execution.
- Actions need to be independent from each other.
- Failure in one action might prevent other actions from executing.
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)
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 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
String.format
.
string
core.format(format, args)
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={})
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](https://github.com/google/re2/wiki/Syntax) 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]+"}
core.merge_import_config
core.merge_import_config(package_path, paths=None, use_consistency_file=False)
string
Package location (ex. 'google3/third_party/java/foo').
paths |glob
or NoneType
Glob of paths to apply merge_import mode, relative to package_path
use_consistency_file |bool
under development
### core.move Moves files between directories and renames filestransformation
core.move(before, after, paths=glob(["**"]), overwrite=False, regex_groups={})
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 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](https://github.com/google/re2/wiki/Syntax) syntax. For example {"x": "[A-Za-z]+"}
transformation
core.remove(paths)
glob
The files to be deleted
transformation
core.rename(before, after, paths=glob(["**"]), overwrite=False, suffix=False)
string
The filepath or suffix to change
after |string
A filepath or suffix to use as replacement
paths |glob
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.
transformation
core.replace(before, after, regex_groups={}, paths=glob(["**"]), first_only=False, multiline=False, repeated_groups=False, ignore=[])
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](https://github.com/google/re2/wiki/Syntax) syntax. For example {"x": "[A-Za-z]+"}
paths |glob
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. Any line that matches any expression in this set, which might otherwise be transformed, will be ignored. Furthermore, it is not possible to ignore a selected text, and replace another, if they exist on the same line. The entire line will be ignored. Note that `ignore` is matched to the whole file, not just the parts that match `before` comparing the to-be-transformed string to the ignore regexes, meaning text outside the transform may be used to determine whether or not to apply a transformation.
mapping_function
core.replace_mapper(mapping, all=False)
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 transformationssequence of transformation
core.reverse(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)
sequence of string
Prefix tag to look for
mapping |dict
Mapping of users/strings
mode |string
Mode for the replace:
glob
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".
transformation
core.transform(transformations, reversal=The reverse of 'transformations', ignore_noop=None, noop_behavior=NOOP_IF_ANY_NOOP)
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.
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.
string
or NoneType
How to handle no-op transformations:
transformation
core.verify_match(regex, paths=glob(["**"]), verify_no_match=False, also_on_reversal=False, failure_message=None)
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](https://github.com/google/re2/wiki/Syntax) syntax.
paths |glob
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 changecore.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)
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_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 NoneType
A glob 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.
destination_files |glob
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:
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
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:
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 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 BarStarlarkDateTime
datetime.fromtimestamp(timestamp=0, tz='America/Los_Angeles')
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')
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 todestination_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 |sequence of string
List of errors that happened during the migration
origin_refs |sequence 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 destinationdestination_reader.copy_destination_files(glob, path=None)
glob
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
bool
destination_reader.file_exists(path)
string
Path to the file.
### destination_reader.read_file Read a file from the destination.string
destination_reader.read_file(path)
string
Path to the file.
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
string
Return the URL of this endpoint.
destination_ref
endpoint.new_destination_ref(ref, type, url=None)
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)
string
The reference.
## feedback.context Gives access to the feedback migration information and utilities. This context is a concrete implementation for feedback migrations.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 |sequence 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)
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)
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")
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:
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.
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 |sequence 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)
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)
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")
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:
dynamic.action_result
feedback.finish_hook_context.success()
## feedback.revision_context
Information about the revision request/resolved for the migration
dict[string, sequence 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)
string
The template to use
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)
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() ## 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=[])
glob
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`
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)
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)
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)
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'])
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.sequence of gerritapi.ChangeInfo
gerrit_api_obj.list_changes(query, include_results=[])
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)
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)
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)
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 changegerritapi.ChangeInfo
gerrit_api_obj.submit_change(change_id)
string
The Gerrit change id.
## gerritapi.AccountInfo Gerrit account information.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.
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.
sequence 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.
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.
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.
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.
sequence 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.
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.
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.string
The name of the target branch.
The refs/heads/ prefix is omitted.
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.
string
The ID of the change in the format "`
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.
sequence of gerritapi.ChangeMessageInfo
Messages associated with the change as a list of ChangeMessageInfo entities.
Only set if messages are requested.
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.
string
The status of the change (NEW, MERGED, ABANDONED).
subject |string
The subject of the change (header line of the commit message).
submit_requirements |sequence 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.
updated |string
The timestamp of when the change was last updated.
gerritapi.AccountInfo
Author of the message as an AccountInfo entity.
Unset if written by the Gerrit system.
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.
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.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 |sequence 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.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
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.sequence 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.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.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.
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 expressionstring
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-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.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)
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
or NoneType
A checker that can check leaks or other checks in the commit created.
**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)
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)
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:
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 will be added to gerrit change reviewer listThe element in the list is: an email, for example: "foo@example.com" or label for example: ${SOME_GERRIT_REVIEWER}. These are under the condition of assuming that users have registered to gerrit 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}"`
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
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_checker`is used, that checker will only apply to API calls.
**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_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 ccorigin
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)
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.
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.
trigger
git.gerrit_trigger(url, checker=None, events=[], allow_submit=False)
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'`
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)
string
Indicates the GitHub repo URL.
checker |checker
or NoneType
A checker for the GitHub API transport.
**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-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. 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)
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.
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.
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
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_checker`is used, that checker will only apply to API calls.
**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.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)
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.
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.
bool
If true, Large File Storage support is enabled for the origin.
### 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)
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.
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
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_checker`is used, that checker will only apply to API calls.
draft |bool
Flag create pull request as draft or not.
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)
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
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
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.
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
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.
trigger
git.github_trigger(url, checker=None, events=[])
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'`
git_integrate
git.integrate(label="COPYBARA_INTEGRATE_REVIEW", strategy="FAKE_MERGE_AND_INCLUDE_FILES", ignore_errors=True)
string
The migration label that will contain the url to the change to integrate.
strategy |string
How to integrate the change:
bool
If we should ignore integrate errors and continue the migration without the integrate
VersionSelector
git.latest_version(refspec_format="refs/tags/${n0}.${n1}.${n2}", refspec_groups={'n0' : '[0-9]+', 'n1' : '[0-9]+', 'n2' : '[0-9]+'})
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](https://github.com/google/re2/wiki/Syntax) 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 repositoriesgit.mirror(name, origin, destination, refspecs=['refs/heads/*'], prune=False, partial_fetch=False, description=None, action=None, origin_checker=None, destination_checker=None)
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.
### git.origin Defines a standard Git origin. For Git specific origins use: `github_origin` or `gerrit_origin`.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)
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.
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.
SetReviewInput
git.review_input(labels={}, message=None, tag=None)
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 repositoriesstring
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 branchgit_merge_result
git.mirrorContext.cherry_pick(branch, commits, add_commit_origin_info=True, merge_parent_number=None, allow_empty=False, fast_forward=False)
string
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)
string
unknown
bool
git.mirrorContext.destination_fetch(refspec, prune=True, depth=None, partial_fetch=False)
sequence of string
bool
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=[])
sequence of string
bool
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)
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")
string
sequence of string
unknown
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)
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)
sequence of string
bool
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)
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")
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:
dict[string, string]
git.mirrorContext.references(refspec=[])
sequence of string
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.
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.
string
The SHA-1 of the commit
state |string
The overall state of all statuses for a commit: success, failure, pending or error
statuses |sequence of github_api_status_obj
List of statuses for the commit
total_count |int
Total number of statuses
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 GitHubgithub_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 GitHubgithub_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
string
Body of the comment
id |long
Comment identifier
user |github_api_user_obj
Comment user
string
Return the URL of this endpoint.
### github_api_obj.add_label Add labels to a PR/issuegithub_api_obj.add_label(number, labels)
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)
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)
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)
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)
string
The name of the reference.
### github_api_obj.get_authenticated_user Get autenticated user info, return null if not foundgithub_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
sequence of github_check_run_obj
github_api_obj.get_check_runs(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)
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)
string
The SHA-1 for which we want to get the combined status
### github_api_obj.get_pull_request_comment Get a pull request commentgithub_api_pull_request_comment_obj
github_api_obj.get_pull_request_comment(comment_id)
string
Comment identifier
### github_api_obj.get_pull_request_comments Get all pull request commentssequence of github_api_pull_request_comment_obj
github_api_obj.get_pull_request_comments(number)
int
Pull Request number
### github_api_obj.get_pull_requests Get Pull Requests for a reposequence of github_api_pull_request_obj
github_api_obj.get_pull_requests(head_prefix=None, base_prefix=None, state="OPEN", sort="CREATED", direction="ASC")
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)
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.sequence of github_api_ref_obj
github_api_obj.get_references()
### github_api_obj.list_issue_comments
Lists comments for an issue
sequence of github_api_issue_comment_obj
github_api_obj.list_issue_comments(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)
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)
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)
string
The git tag to use for the release.
github_api_obj.post_issue_comment(number, comment)
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 foundgithub_api_pull_request_obj
github_api_obj.update_pull_request(number, title=None, body=None, state=None)
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)
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 GitHubstring
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
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
string
The name of the reference
sha |string
The sha of the reference
url |string
The url of the reference
string
Label for the revision
ref |string
Reference
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 GitHubstring
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.
string
Login of the user
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-rungithub_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 |sequence 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.
sequence 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-rungithub_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-releasegithub_create_release_obj
github_create_release_obj.set_draft(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)
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)
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)
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)
string
Body for the release
### github_create_release_obj.with_commitish Set the commitish to be used for the release. Defaults to HEADgithub_create_release_obj
github_create_release_obj.with_commitish(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)
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-releaseint
Release id
tarball |string
Tarball Url
zip |string
Zip Url
glob
glob(include, exclude=[])
sequence of string
The list of glob patterns to include
exclude |sequence of string
The list of glob patterns to exclude
author
new_author(author_string)
string
A string representation of the author with the form 'name
ChangeMessage
parse_message(message)
string
The contents of the change message
## 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)
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.
### go.go_proxy_version_list Returns go proxy version list objectGoProxyVersionList
go.go_proxy_version_list(module, ref=None)
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.
origin
hg.origin(url, ref="default")
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:
sequence of HtmlElement
html.xpath(content, expression)
string
The HTML content
expression |string
XPath expression to select elements
## Issue Github issue objectgithub_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
transformation
metadata.add_header(text, ignore_label_not_found=False, new_line=True)
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`
transformation
metadata.expose_label(name, new_name=label, separator="=", ignore_label_not_found=True, all=False, concat_separator=None)
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.
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)
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>'
|bool
If the transform is automatically reversible. Workflows using the reverse of this transform will be able to automatically map values to keys.
|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 = [])`.
|bool
Fail if a mapping cannot be found. Helps discovering early authors that should be in the map
|bool
Same as fail_if_not_found but when the transform is used in a inverse workflow.
|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.
transformation
metadata.map_references(before, after, regex_groups={}, additional_import_labels=[])
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](https://github.com/google/re2/wiki/Syntax) 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.
transformation
metadata.remove_label(name)
string
The label name
transformation
metadata.replace_message(text, ignore_label_not_found=False)
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.
transformation
metadata.restore_author(label='ORIGINAL_AUTHOR', separator="=", search_all_changes=False)
string
The label to use for restoring the author
|string
The separator to use between the label and the value
|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="=")
string
The label to use for storing the author
|string
The separator to use between the label and the value
### metadata.scrubber Removes part of the change message using a regextransformation
metadata.scrubber(regex, msg_if_no_match=None, fail_if_no_match=False, replacement='')
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.
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)
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
|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
transformation
metadata.use_last_change(author=True, message=True, default_message=None, use_merge=True)
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)
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.
string
Origin reference ref
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='')
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.**
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.
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)
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.
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
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
path.relativize(other)
Path
The path to relativize against this path
### path.remove Delete selfpath.remove()
### path.resolve
Resolve the given path against this path.
Path
path.resolve(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)
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 directorypath.rmdir(recursive=False)
bool
When true, delete descendants of self and of siblings
## PathAttributes Represents a path attributes like size.int
The size of the file. Throws an error if file size > 2GB.
symlink |bool
Returns true if it is a symlink
## re2 Set of functions to work with regexes in Copybara. ### re2.compile Create a regex patternre2_pattern
re2.compile(regex)
string
string
re2.quote(string)
string
int
re2_matcher.end(group=0)
int
or string
bool
re2_matcher.find(start=None)
int
or NoneType
The input position where the search begins
### re2_matcher.group Return a matching groupstring
re2_matcher.group(group=0)
int
or string
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)
string
string
re2_matcher.replace_first(replacement=0)
string
int
re2_matcher.start(group=0)
int
or string
re2_matcher
re2_pattern.matcher(input)
string
bool
re2_pattern.matches(input)
string
remote_http_file.GitHubArchive
remotefiles.github_archive(project=[], revision=[], type='TARBALL')
string
The GitHub project from which to load the file, e.g. google/copybara
revision |string
The revision to download from the project, typically a commit SHA1.
type |string
Archive type to download, options are 'TARBALL' or 'ZIP'.
**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 ', message='Placeholder message', unpack_method='AS_IS', archive_source='', version_list=None, origin_version_selector=None, version_resolver=None)
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', 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.
**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)
string
The version requirement
## SetReviewInput Input for posting a review to Gerrit. See https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#review-inputlong
StarlarkDateTime.in_epoch_seconds()
### StarlarkDateTime.strftime
Returns a string representation of the StarlarkDateTime object with your chosen formatting
string
StarlarkDateTime.strftime(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.
## 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()
TomlContent
toml.parse(content)
string
TOML content to be parsed
unknown
TomlContent.get(key)
string
The dotted key expression
unknown
TomlContent.get_or_default(key, default)
string
The dotted key expression
default |unknown
The default value to return if the key isn't found.
core
.core.dynamic_transform
.
bool
Whether this status has the value NO-OP.
is_success |bool
Whether this status has the value SUCCESS.
dynamic transform
.
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
ctx.add_label(label, value, separator="=", hidden=False)
string
The label to add
value |string
The new value for the label
separator |string
The separator to use for the label
|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 descriptionctx.add_or_replace_label(label, value, separator="=")
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 paragraphctx.add_text_before_labels(text)
string
ctx.create_symlink(link, target)
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)
string
The template to use
sequence of string
ctx.find_all_labels(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)
string
The label to find
### ctx.list List files in the checkout/work directory that matches a globsequence of Path
ctx.list(paths)
glob
A glob representing the paths to list
### ctx.new_path Create a new pathPath
ctx.new_path(path)
string
The string representing the path, relative to the checkout root directory
### ctx.noop The status returned by a no-op Transformationtransformation_status
ctx.noop(message)
string
string
ctx.now_as_string(format="yyyy-MM-dd", zone="UTC")
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)
Path
The Path to read from
### ctx.remove_label Remove a label from the message if presentctx.remove_label(label, whole_message=False)
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 messagectx.replace_label(label, value, separator="=", whole_message=False)
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']))
ctx.run(core.move("foo", "bar"))
unknown
ctx.run(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 changectx.set_author(author)
author
ctx.set_executable(path, value)
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 changectx.set_message(message)
string
transformation_status
ctx.success()
ctx.write_path(path, content)
Path
The Path to write to
content |string
The content of the file
## VersionSelector Select a version from a list of versionsunknown
xml.xpath(content, expression, type)
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-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. `--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.