Hello World

Hello World

Welcome to your first Copybara tutorial! By the end of this guide, you’ll understand how Copybara works by syncing files between two local folders.

No GitHub account or remote servers needed - everything runs on your computer.

What You’ll Build

You’ll create a workflow that:

1. Reads files from a “source” folder
2. Replaces placeholder text (like MYCOMPANY → Acme Corp)
3. Writes the transformed files to a “destination” folder

This is the same pattern used for real-world tasks like publishing internal code to GitHub.

Before You Start

Make sure you have:

• Java 11 or newer - Check with java -version
• Git - Check with git --version
• Copybara JAR file - See Installation

Tip

If you haven’t installed Copybara yet, the easiest way is to download the JAR from the GitHub releases page.

Project Setup

We’ll create this folder structure:

• Directorycopybara-tutorial/

  • Directorysource/ The folder we’ll read from (origin)

    • README.md
    • Directorysrc/

      • app.py
  • Directorydestination/ The folder we’ll write to (empty for now)

    • …
  • copy.bara.sky Your Copybara configuration

Create the folders

Open your terminal and run:

mkdir -p ~/copybara-tutorial/source/src
mkdir -p ~/copybara-tutorial/destination
cd ~/copybara-tutorial

Create the source files

Create source/README.md with this content:

source/README.md

# Welcome to MYPROJECT

This project is built by MYCOMPANY.

For help, contact support@internal.mycompany.com

Create source/src/app.py with this content:

source/src/app.py

# MYPROJECT - Main Application
# Copyright MYCOMPANY

def main():
    print("Hello from MYPROJECT!")

if __name__ == "__main__":
    main()

Note

You can create these files using any text editor - VS Code, Sublime, nano, vim, or even Notepad.

Initialize Git repositories

Copybara works with Git repositories, so we need to initialize both folders:

# Initialize the source repository
cd ~/copybara-tutorial/source
git init
git add .
git commit -m "Initial commit"

# Initialize the destination repository
cd ~/copybara-tutorial/destination
git init
git commit --allow-empty -m "Initial commit"

Note

The destination needs an initial commit (even an empty one) so Copybara has something to compare against.

Write the Configuration

Now for the main part - the Copybara configuration file.

Create copy.bara.sky in the copybara-tutorial folder:

copy.bara.sky

sourceUrl = "file://" + "/Users/YOURNAME/copybara-tutorial/source"
destinationUrl = "file://" + "/Users/YOURNAME/copybara-tutorial/destination"

core.workflow(
    name = "default",

    origin = git.origin(
        url = sourceUrl,
        ref = "main",
    ),

    destination = git.destination(
        url = destinationUrl,
        fetch = "main",
        push = "main",
    ),

    authoring = authoring.overwrite("Tutorial <tutorial@example.com>"),

    transformations = [
        core.replace(
            before = "MYCOMPANY",
            after = "Acme Corp",
        ),
        core.replace(
            before = "MYPROJECT",
            after = "My Awesome App",
        ),
        core.replace(
            before = "internal.mycompany.com",
            after = "example.com",
        ),
    ],
)

Important: Update the paths!

Replace YOURNAME with your actual username. For example:

• macOS: /Users/alice/copybara-tutorial/source
• Linux: /home/alice/copybara-tutorial/source

Find your home folder with echo $HOME in the terminal.

Understanding the configuration

Let’s break down what each part does:

Part	What it does
origin	Where to read files from (our source folder)
destination	Where to write files to (our destination folder)
ref = "main"	Which Git branch to use
authoring	Who to credit as the commit author
transformations	Changes to make to the files

The core.replace() transformation finds text and replaces it - like find-and-replace in a text editor, but for your entire project.

Run Copybara

Now let’s run it! From the copybara-tutorial folder:

cd ~/copybara-tutorial

java -jar copybara.jar migrate copy.bara.sky default --force

About the flags

• migrate - The command to run a sync
• copy.bara.sky - Your configuration file
• default - The workflow name (we named it “default” in the config)
• --force - Required for the first run

See all available flags in the CLI Reference.

Don’t have copybara.jar in this folder? Use the full path:

java -jar ~/Downloads/copybara_deploy.jar migrate copy.bara.sky default --force

You should see output ending with:

Migration finished successfully.

Check the Results

Let’s see what Copybara created:

cd ~/copybara-tutorial/destination
ls -la

You should see README.md and src/app.py.

Now check the content:

cat README.md

Output:

# Welcome to My Awesome App

This project is built by Acme Corp.

For help, contact support@example.com

The placeholders were replaced:

Before	After
MYPROJECT	My Awesome App
MYCOMPANY	Acme Corp
internal.mycompany.com	example.com

Check the Python file too:

cat src/app.py

# My Awesome App - Main Application
# Copyright Acme Corp

def main():
    print("Hello from My Awesome App!")

if __name__ == "__main__":
    main()

What Happened?

Copybara:

1. Read all committed files from the source Git repository
2. Applied transformations - replaced the placeholder text
3. Wrote the transformed files to the destination
4. Committed the changes in the destination repository

Make a Change and Sync Again

Let’s see incremental sync in action. Edit the source file:

cd ~/copybara-tutorial/source

Add a new file source/src/utils.py:

source/src/utils.py

# MYPROJECT utilities
# Author: MYCOMPANY Team

def helper():
    return "I help MYPROJECT run smoothly!"

Commit the change:

git add src/utils.py
git commit -m "Add utilities"

Run Copybara again (no --force needed now):

cd ~/copybara-tutorial
java -jar copybara.jar migrate copy.bara.sky default

Check the destination:

cat ~/copybara-tutorial/destination/src/utils.py

The new file appears with all replacements applied - only the new changes were synced.

Troubleshooting

”Cannot find reference ‘main’”

Your Git might use master as the default branch. Either:

Option A: Change the config to use master:

ref = "master",
fetch = "master",
push = "master",

Option B: Rename your branch to main:

cd ~/copybara-tutorial/source
git branch -m master main
cd ~/copybara-tutorial/destination
git branch -m master main

“Nothing to migrate”

This means source and destination are already in sync. Make a change in the source, commit it, then run Copybara again.

”Cannot find workflow ‘default’”

Make sure your workflow in copy.bara.sky has name = "default", or use the name you chose:

java -jar copybara.jar migrate copy.bara.sky YOUR_WORKFLOW_NAME --force

Java errors about paths

Double-check that:

1. The paths in your config use file:// prefix
2. The paths are absolute (start with /)
3. You replaced YOURNAME with your actual username
4. Both Git repos have at least one commit

What’s Next?

Now that you understand the basics:

• Open Source a Project - A real-world example with GitHub
• CLI Reference - All available commands and flags
• Transformations - All the ways to modify files
• Core Concepts - Deeper understanding of Copybara