swift-mirror/utils/update_checkout

update-checkout

update-checkout is Swift's multi repository management tool. It allows to clone and update all the required repositories to build the Swift toolchain based on the update-checkout-config.json configuration file.

Installation

update-checkout does not have any dependencies apart from Python 3.7 or more recent. To run it, clone the swift repository and run the following command to print the help output:

./swift/utils/update-checkout -h

Usage

The following commands assume you have a working Python 3 installation and that you have already cloned the swift repository.

Cloning the repositories and checking out a specific scheme

To clone the repositories for the release/6.2 scheme, run the following command:

./swift/utils/update-checkout --clone --scheme release/6.2

The command above will use HTTPS to clone the repositories. Use --clone-with-ssh to clone with SSH instead:

./swift/utils/update-checkout --clone-with-ssh --scheme release/6.2

You can skip repositories by adding the --skip-repository argument:

./swift/utils/update-checkout --clone-with-ssh --scheme release/6.2 --skip-repository llvm-project --skip-repository swift

Updating or switching between schemes

To update all the repositories after they have been cloned or to switch to another scheme, run:

./swift/utils/update-checkout --scheme main

If you have changes in any of the repositories, you can stash or clean them before updating. Please refer to the help for the details as to how --clean and --stash differ.

./swift/utils/update-checkout --scheme main --clean

Resetting all repositories to the remote state

To reset the branches from each repositories to the state of the matching remote branch, run the following command:

./swift/utils/update-checkout --reset-to-remote --scheme release/6.2

To reset the branches to a tag rather than a scheme, run:

./swift/utils/update-checkout --reset-to-remote --tag swift-6.2.1-RELEASE

You can skip repositories by adding the --skip-repository argument:

./swift/utils/update-checkout --reset-to-remote --scheme release/6.2 --skip-repository llvm-project --skip-repository swift

Matching timestamps

To checkout the commits that most closely match the timestamp of the checked out commit of the Swift repository, run:

./swift/utils/update-checkout --scheme release/6.2 --match-timestamp

Configuration

Clone URLs

By default, the URL a repository is cloned from is formed by interpolating its remote id into the top-level ssh-clone-pattern or https-clone-pattern, depending on whether --clone-with-ssh was passed:

"ssh-clone-pattern": "git@github.com:%s.git",
"https-clone-pattern": "https://github.com/%s.git",
"repos": {
    "swift": { "remote": { "id": "swiftlang/swift" } }
}

A repository that does not live where the clone patterns point can override its URL. Use url when the same URL should be used for both protocols, or ssh-url / https-url to override only the URL for a given protocol:

"repos": {
    "boringssl": {
        "remote": {
            "id": "google/boringssl",
            "url": "https://boringssl.googlesource.com/boringssl"
        }
    },
    "swift-corelibs-xctest": {
        "remote": {
            "id": "swiftlang/swift-corelibs-xctest",
            "ssh-url": "git@github.com:swiftlang/swift-corelibs-xctest.git",
            "https-url": "https://github.com/swiftlang/swift-corelibs-xctest.git"
        }
    }
}

When both a protocol-specific override and url are present, the protocol-specific one wins for its protocol. An override for the other protocol is still preferred over the interpolated URL, so a repository that only specifies https-url is cloned over HTTPS even with --clone-with-ssh.

Testing

update-checkout has both unit and end to end tests located in the tests directory. You can run them with the following command:

python3 ./swift/utils/update_checkout/run_tests.py

The tests are also part of the check-swift target, which means they run on CI along the other Swift tests.

Contributing

Before contributing, please read our main guide

LICENSE

See LICENSE for license information.

Code of Conduct

See Swift.org Code of Conduct for Code of Conduct information.