gitspork

README

When a fork just ain't good enough

Solutions like git forks or templates are useful, but fall short in certain cases when staying up-to-date with their upstreams. Enter gitspork.

---

⚠ This tool is still in pre-release development. Official releases will be made here in this repo when it is considered ready for production use.

---

Getting Started

First, quickly some terminology:

• upstream: a repo that contains some standards, utility, etc. to be distributed to other repos over time. Think of an "upstream" like a git template or a git fork upstream.
• downstream: a repo that integrates with an upstream repo to reuse its standards and utility. Think of a downstream like a repo that has been forked from another git repo, or generated from a git template.

Install

Download the appropriate binary from the Github releases, and install on your system's PATH.

Simple Demo

In an empty directory on your machine:

% git init
% gitspork integrate \
  --upstream-repo-url https://github.com/rockholla/gitspork \
  --upstream-repo-subpath ./docs/examples/simple/upstream \
  --upstream-repo-version main \
  --downstream-repo-path ./

You'll see that your repo has been initially integrated with one of our example upstreams in this repo. Start to explore your repo source now that it's been integrated, and learn about each of the advanced, yet simple integration types at play here, controlled by the upstream .gitspork.yml configuration.

• Upstream-Owned Resources: those that the upstream controls entirely, and will overwrite in downstreams on each integration
• Downstream-Owned Resources: the gitspork integration will make sure these types of files get bootstrapped in the downstream, but then let's the downstream take over full ownership from there
• Co-Owned Resources to be Merged (Generic): certain files can be owned by both the upstream and and downstream, upstream defining blocks surrounded by ::gitspork::begin-upstream-owned-block/::gitspork::end-upstream-owned-block, typically in comments to maintain upstream-owned content alongside downstream-owned content
• Co-Owned Resources to be Merged (Structured Data): json/yaml resources that can be merged in a structured way, with a switch to say whether upstream or downstream values should be preferred/take precedence when doing the merging
• Migrations Support: some ability for the upstream to instruct downstream repos in particular migration-related operations:
  • Exec: arbitrary commands or scripts defined in the upstream to run against the downstream either pre integrate or post integrate

Initialize a Repo as a gitspork Upstream

% gitspork init

This will simply initialize a .gitspork.yml file so you can begin configuring how your upstream should share out and integrate w/ downstreams.

Additional Documentation

See ./docs for further information on how gitspork works and usage.