mirror of
https://github.com/splitsh/lite.git
synced 2024-06-06 07:42:22 +02:00
rewrote README
This commit is contained in:
parent
2ba69378ab
commit
ac76236d44
136
README.md
136
README.md
|
@ -1,18 +1,23 @@
|
|||
Monolithic Repositories to Many Repositories made easy
|
||||
======================================================
|
||||
Git Subtree Splitter
|
||||
====================
|
||||
|
||||
**tl;dr**: **splitsh-lite** is a replacement for the `subtree split` Git
|
||||
built-in command that is much faster and has more features at the same time.
|
||||
**splitsh-lite** replaces the `subtree split` Git built-in command to make
|
||||
**splitting a monolithic repository** to read-only standalone repositories
|
||||
**easy and fast**.
|
||||
|
||||
When starting a new project, do you store all the code in one monolithic
|
||||
repository? Or are you creating many repositories?
|
||||
Why do I need this tool?
|
||||
------------------------
|
||||
|
||||
Both strategies work well but both have drawbacks as well. **splitsh** helps use
|
||||
both strategies at the same time by providing tools that automatically
|
||||
synchronize a mono repository to many repositories.
|
||||
When starting a project, do you store all the code in one repository? Or are
|
||||
you creating many standalone repositories?
|
||||
|
||||
**splitsh-lite** is a sub-project with the goal of providing a faster replacement
|
||||
of the `git subtree split` command.
|
||||
Both strategies work well and both have drawbacks as well. **splitsh** helps
|
||||
use both strategies by providing tools that automatically **synchronize a
|
||||
monolithic repository to standalone repositories** in real-time.
|
||||
|
||||
**splitsh-lite** is a sub-project that provides a faster implementation of the
|
||||
`git subtree split` command, which helps create standalone repositories for one
|
||||
or more sub-directories of a main repository.
|
||||
|
||||
If you want to learn more about monorepo vs manyrepos, watch this [4-minute
|
||||
lightning talk](http://www.thedotpost.com/2016/05/fabien-potencier-monolithic-repositories-vs-many-repositories)
|
||||
|
@ -21,31 +26,10 @@ I gave at dotScale
|
|||
or watch the longer version from
|
||||
[DrupalCon](https://www.youtube.com/watch?v=4w3-f6Xhvu8).
|
||||
|
||||
The main **splitsh-lite** feature is its ability to create a branch in a repository
|
||||
from one or many directories.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
Install libgit2:
|
||||
|
||||
```bash
|
||||
go get -d github.com/libgit2/git2go
|
||||
cd $GOPATH/src/github.com/libgit2/git2go
|
||||
git checkout next
|
||||
git submodule update --init
|
||||
make install
|
||||
```
|
||||
|
||||
Compiling
|
||||
|
||||
```bash
|
||||
go get github.com/splitsh/lite
|
||||
go build -o splitsh-lite github.com/splitsh/lite
|
||||
```
|
||||
|
||||
If everything goes fine, a `splitsh-lite` binary should be available in the
|
||||
current directory.
|
||||
The fastest way to get started is to download a [binary][4] for your platform.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
@ -74,17 +58,17 @@ splitsh-lite --prefix=lib/ --target=branch-name
|
|||
```
|
||||
|
||||
If new commits are made on the repository, update the split by running the same
|
||||
command again. Updates are much faster as **splitsh-lite** keeps a cache of already
|
||||
split commits. Caching is possible as **splitsh-lite** guarantees that two splits of
|
||||
the same code always results in the same history and the same `sha1`s for each
|
||||
commit.
|
||||
command again. Updates are much faster as **splitsh-lite** keeps a cache of
|
||||
already split commits. Caching is possible as **splitsh-lite** guarantees that
|
||||
two splits of the same code always results in the same history and the same
|
||||
`sha1`s for each commit.
|
||||
|
||||
By default, **splitsh-lite** splits the current checkout-ed branch but you can split
|
||||
a different branch by passing it explicitly with `--origin` (mandatory when
|
||||
splitting a bare repository):
|
||||
By default, **splitsh-lite** splits the current checkout-ed branch but you can
|
||||
split a different branch by passing it explicitly via the `--origin` flag
|
||||
(mandatory when splitting a bare repository):
|
||||
|
||||
```bash
|
||||
splitsh-lite --prefix=lib/ --origin=origin/1.0
|
||||
splitsh-lite --prefix=lib/ --origin=origin/master
|
||||
```
|
||||
|
||||
You don't even need to run the command from the Git repository directory if you
|
||||
|
@ -97,34 +81,70 @@ splitsh-lite --prefix=lib/ --origin=origin/1.0 --path=/path/to/repo
|
|||
Available options:
|
||||
|
||||
* `--prefix` is the prefix of the directory to split; you can put the split
|
||||
contents in a directory by using the `--prefix=from:to` syntax; splitting
|
||||
several directories is also possible by passing multiple `--prefix` options;
|
||||
contents in a sub-directory of the target repository by using the
|
||||
`--prefix=from:to` syntax; split several directories by passing multiple
|
||||
`--prefix` flags;
|
||||
|
||||
* `--path` is the path to the repository to split (current directory by default);
|
||||
* `--path` is the path of the repository to split (current directory by default);
|
||||
|
||||
* `--origin` is the Git reference for the origin (can be any Git reference
|
||||
like `HEAD`, `heads/xxx`, `tags/xxx`, `origin/xxx`, or any `refs/xxx`);
|
||||
|
||||
* `--target` creates a reference for the tip of the split (can be any Git reference
|
||||
like `HEAD`, `heads/xxx`, `tags/xxx`, `origin/xxx`, or any `refs/xxx`);
|
||||
* `--target` creates a reference for the tip of the split (can be any Git
|
||||
reference like `HEAD`, `heads/xxx`, `tags/xxx`, `origin/xxx`, or any
|
||||
`refs/xxx`);
|
||||
|
||||
* `--progress` displays a nice progress bar during the split;
|
||||
* `--progress` displays a progress bar;
|
||||
|
||||
* `--quiet` suppresses all output on stderr (useful when run from an automated
|
||||
script).
|
||||
script);
|
||||
|
||||
* `--scratch` flushes the cache (useful when a branch is force pushed or in
|
||||
case of corruption)
|
||||
case of a cache corruption);
|
||||
|
||||
* `--git` simulates old versions of `git subtree split`. **splitsh** generates
|
||||
the same `sha1`s as the latest version of Git by default (`latest`).
|
||||
Simulate old versions of Git by using `<1.8.2` or `<2.8.0`.
|
||||
Migrating from `git subtree split`
|
||||
----------------------------------
|
||||
|
||||
**splitsh** provides more features including a sanity checker, GitHub integration
|
||||
for real-time splitting, tagging management and synchronization, and more.
|
||||
It has been used by the Symfony project for many years but the tool is not yet
|
||||
ready for Open-Source. Stay tuned!
|
||||
Migrating from `git subtree split` to `splith-lite` is easy as both tools
|
||||
generate the same `sha1`s.
|
||||
|
||||
However, note that older versions of `git subtree split` used broken
|
||||
algorithms, and so generated different `sha1`s than the latest version. You can
|
||||
simulate those version via the `--git` flag. Use `<1.8.2` or `<2.8.0` depending
|
||||
on which version of `git subtree split` you want to simulate.
|
||||
|
||||
Manual Installation
|
||||
-------------------
|
||||
|
||||
If you want to contribute to `splitsh-lite` or use it as a library, you first
|
||||
need to install `libgit2`:
|
||||
|
||||
```bash
|
||||
go get -d github.com/libgit2/git2go
|
||||
cd $GOPATH/src/github.com/libgit2/git2go
|
||||
git checkout next
|
||||
git submodule update --init
|
||||
make install
|
||||
```
|
||||
|
||||
Then, compile `splitsh-lite`:
|
||||
|
||||
```bash
|
||||
go get github.com/splitsh/lite
|
||||
go build -o splitsh-lite github.com/splitsh/lite
|
||||
```
|
||||
|
||||
If everything goes fine, a `splitsh-lite` binary should be available in the
|
||||
current directory.
|
||||
|
||||
Full-Version
|
||||
------------
|
||||
|
||||
The full version of **splitsh** provides more features including a sanity
|
||||
checker, GitHub integration for real-time splitting, tag management and
|
||||
synchronization, and more. It has been used by the Symfony project for many
|
||||
years but the tool is not yet ready for Open-Source. Stay tuned!
|
||||
|
||||
If you think that your Open-Source project might benefit from the full version
|
||||
of splitsh, send me an email and I will consider splitting your project for free
|
||||
on my servers (like I do for Symfony and Laravel).
|
||||
of splitsh, send me an email and I will consider splitting your project for
|
||||
free on my servers (like I do for Symfony and Laravel).
|
||||
|
|
Loading…
Reference in a new issue