NOTE: This project is no longer maintained. Meta has switched to using a (currently) closed-source solution to this that we hope to release in the future. Existing Open Source users can check out Copybara.
FBShipIt is a library written in Hack for copying commits from one repository to another.
For example, Meta uses it to:
- copy commits from our monolithic Mercurial repository to project-specific GitHub repositories
- sync changes from project specific repos like CPython and the linux kernel
- Import changes from PyTorch into our Mercurial monorepo
- read from Git or Mercurial (hg) repositories
- write to Git or Mercurial (hg) repositories
- remove files or directories matching certain patterns
- remove/rewrite sections of commit messages
- modify commit authors (for example, if all internal commits are authored by employees, restore original authors for GitHub pull requests)
FBShipIt has been primarily designed for branches with linear histories; in particular, it does not understand merge commits.
$ composer require facebook/fbshipit
There are three main concepts: phases, changesets, and filters.
ShipItPhase objects represent a high-level action, such as
'clone this repository', 'pull this repository',
'sync changesets', and 'push repository'.
Within the sync phase, a ShipItChangeset is an immutable
object representing a commit.
Filters are functions that take a Changeset, and return a new, modified one.
ShipItCreateNewRepoPhase: creates a new Git repository with an 'initial commit'. Skipped unless--create-new-repopassed.ShipItAssertValidFilterPhase: make sure that the filter is consistent with the specified roots.ShipItGitHubInitPhase: create and configure a github clone.ShipItPullPhase: pull in any new changes to a repository.ShipItPushPhase: push local changes to the destination repository.ShipItSyncPhase: copy commits from the source repository to the destination repository.ShipItVerifyRepoPhase: check that the destination repository matches the source repository and filter. Skipped unless--verifyor--create-fixup-patchis passed.
You need to construct:
- a
ShipItManifestobject, defining your default working directory, and the directory names of your source and destination repositories - a list of phases you want to run
- a pipeline of filters, assuming you are using the
ShipItSyncPhase
Filters are provided for common operations - the most frequent are:
ShipItPathFilters::moveDirectories(string $changeset, dict<string, string> $mapping): apply patches to a different directory in the destination repositoryShipItPathFilters::stripPaths(string $changeset, vec<string> $patterns, vec<string> $exception_patterns = vec[]): remove any modifications to paths matching$patterns, unless they match something in$exception_patterns.
See the demo/ directory for a simple example to start from.
Add ShipItCreateNewRepoPhase to your phase list (after source init and pull
phases), then run:
hhvm my_script.hack --create-new-repo
This will give you the path to a git repository with a single commit; you can then push it to your destination.
When there is at least one relevant commit in the source repository that is not in the destination repository, run:
hhvm my_script.hack --first-commit=FIRST_UNSYNCED_COMMIT_ID_GOES_HERE
Run your script with no arguments; FBShipIt adds tracking information to the commits it creates, so will automatically sync any new commits.
We recommend splitting out common filters and phase setup to separate classes, and for these to be re-used between your projects. For an example from Facebook's usage, see FBCommonFilters
Some other code that might be useful for configuring FBShipIt can be found in fb-examples/.
FBShipIt is MIT-licensed.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent