It would be better if it said something like 'foo' is not a recognized splash command.

+

+

Here's what git does:

+

$ git foo

+

git: 'foo' is not a git command. See 'git --help'.

Revision as of 16:53, 23 January 2014

Splash is a tool to manage patch series and
dependencies between them in git. A 'splash' is a patch series. The
'Splashfile' defines all of our 'splashes' and how they fit together.

Splash is intended to make it easier to work on separate branches of a git
tree, merging them and unmerging them at will, in order to keep changes
in separate branches but easily integrate them for final work.

Splash keeps track of dependencies and order of merging between branches.

Usage help

Simply executing splash.py without parameters or with the parameter
'help' should at least give you usage.

[ FIXTHIS - put usage here. ]

Splash commands

[ FIXTHIS - expand upon each command here]

abort - abort the current operation

checkout - checkout the specified splash

continue - continue the current operation

begin - (re)start specified splash

fetch - fetch tree up until specified splash

start - ??

status - display all splashes

log - shwo current log-graph up to base

merge - merge another splash onto this one (or this one onto another?)

unmerge - remove another splash from this one (or this one from another?)

rebuild - rebuild tree

sync - rebuild tree and push all dependent splashes to remote

help. -h or --help - print usage and exit

Options:

-l or --list - list splashes and exit

-b or --base - specify base splash

-v or --verbose - be verbose

Splash setup

Splash includes the splash.py program and a configuration file called 'Splashfile'.

The configuration file contains descriptions of the 'splashes' in a particular repository.
To use splash, symlink the Splashfile to the working kernel directory.
Put the splash.py program on your path (usually somewhere like ~/bin.

If you change dependencies in the Splashfile, such as adding
'my-feature' to the rhine/int deps, you'll need to execute:

$ splash rebuild rhine/int

Recovering from errors

Splash has its own batch parser, similar to the one in a git
interactive rebase. Previous to splash, the developers used to use
'git interactive rebase', but it is slow, and you can't batch rebases this way.

If a command fails in any way (other than argument parsing), you can recover by
executing:

$ splash.py abort

or, to try the operation again, do:

$ splash.py continue

In general, Sony keeps topic branches in git under .git/refs/topics/<developer_name>/foo
According to many tools these aren't valid refs because they aren't under refs/heads/
or refs/tags/.

Retrieving a topic branch and making a local branch

You can download and have all the splashes as local refs in one of
the following ways:

but keep in mind that these branches will need to be updated every time
you change anything in splash. You can also make the ref a symlink
instead to fix this, but I'll leave that as an exercise for the reader.

WIP documentation

Questions

Q: what is the 'splash.remote' needed by splash?

Having Splashfile and splash.py as the only elements in the kernel repository is
a weird. They are not present when the actual source is present, until you
copy them out (then link the Splashfile back in again?) ??? It seems like there
should be a well-known place for this, either outside the tree or in another repository.
Why is the Splashfile kept where it is in the repository?

Possible answers:

A. outside the tree is a pain - it's too removed from the code

B. in another repository is a pain - it's removed from the code

C. inside any branch is a pain - you'd have to check out that branch, and there's no way to synchronize the Splashfile between branches.

Does splash modify the Splashfile itself when you execute commands?

Is Splashfile like a quilt 'series' file, showing what things CAN be added, or
like an 'applied' file, showing what things are currently added?

If it's like a series file, is there anything like an 'applied' file?

How is splash similar or different to stacked git?

What do you do with conflicts? What if the branches can't be automatically merged?
Is there any facility for keeping track of conflict resolution patches, that are outside
of both the feature branch and the integration branch?

How do I set up a new splash tree?

Bugs

Splash can not show help (-h,--help,help) in some situations

Doing 'splash.py -h' in a repostiroy without a splash.remote results in: