Difference between revisions of "Splash"

From eLinux.org
Jump to: navigation, search
(fix more stuff)
m (removing an extra 'to')
 
(7 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
Splash is a tool to manage patch series and
 
Splash is a tool to manage patch series and
dependencies between them in git.  A 'splash' is a patch series.  The
+
dependencies between them in git.  A 'splash' is defined by a set of branches that
'Splashfile' defines all of our 'splashes' and how they fit together.
+
can be applied to (integrated into) a working branch of a source tree.  The
 +
'Splashfile' defines all of the '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.
 +
 
 +
It has similarities to quilt and stacked-git.  But both of those only
 +
support a single series of patches.  Splash supports a hierarchy of
 +
nested branches, each containing multiple sets of commits.
  
 
== Usage help ==
 
== Usage help ==
Line 12: Line 23:
 
=== Splash commands ===
 
=== Splash commands ===
  
[ FIXTHIS - put list of commands here ]
+
[ FIXTHIS - expand upon each command here]
 +
 
 
* abort - abort the current operation
 
* abort - abort the current operation
 
* checkout - checkout the specified splash
 
* checkout - checkout the specified splash
Line 26: Line 38:
 
* sync - rebuild tree and push all dependent splashes to remote
 
* sync - rebuild tree and push all dependent splashes to remote
 
* help. -h or --help - print usage and exit
 
* help. -h or --help - print usage and exit
 +
 +
Options:
 
* -l or --list - list splashes and exit
 
* -l or --list - list splashes and exit
 
* -b or --base - specify base splash
 
* -b or --base - specify base splash
 
* -v or --verbose - be verbose
 
* -v or --verbose - be verbose
 
  
 
== Splash setup ==
 
== Splash setup ==
Line 41: Line 54:
  
 
  $ splash.py fetch <splash_name>
 
  $ splash.py fetch <splash_name>
 +
 +
== Splash workflow ==
 +
As a general rule, working with splash works like so:
 +
 +
$ splash.py fetch <splash_name>
 +
  # edit Splashfile to add splash 'my-feature'
 +
$ splash.py start my-feature
 +
  # make / add commits
 +
$ git update-ref refs/splash/my-feature HEAD
 +
$ splash.py push my-feature
 +
 +
At any point you can also do:
 +
 +
$ splash.py merge rhine/int
 +
  # test
 +
$ splash.py unmerge rhine/int
 +
 +
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 ===
 
=== Recovering from errors ===
Line 65: Line 100:
 
the following ways:
 
the following ways:
  
* $ splash.py fetch # or fetch-all or fetchall; fetches all splashes
+
$ splash.py fetch # or fetch-all or fetchall; fetches all splashes
* $ splash.py fetch rhine/int # for all splashes rhine/int depends on
+
or
* $ git fetch origin $(for ref in `sed -n '/^ref/x;s/ref\s*=\s*//p' Splashfile`; do
+
$ splash.py fetch rhine/int # for all splashes rhine/int depends on
 +
or
 +
  $ git fetch origin $(for ref in `sed -n '/^ref/x;s/ref\s*=\s*//p' Splashfile`; do
 
         echo "$ref:refs/heads/${ref:12}"; done)  # poor man's splash
 
         echo "$ref:refs/heads/${ref:12}"; done)  # poor man's splash
  
Line 82: Line 119:
 
This replaced my retrieval of a topic branch:
 
This replaced my retrieval of a topic branch:
  
  $ git fetch origin refs/topics/<dev_name>/<splash_name>
+
  $ git fetch origin refs/topics/<developer_name>/<topic_branch_name>
 
  $ git checkout -b <local_branch_name> FETCH_HEAD
 
  $ git checkout -b <local_branch_name> FETCH_HEAD
  
== Splash workflow ==
+
=== WIP documentation ===
As a general rule, working with splash works like so:
+
 
 +
== Questions ==
  
$ splash.py fetch <splash_name>
+
* Q: what is the 'splash.remote' needed by splash?
  # edit Splashfile to add splash 'my-feature'
 
$ splash.py start my-feature
 
  # make / add commits
 
$ git update-ref refs/splash/my-feature HEAD
 
$ splash.py push my-feature
 
  
At any point you can also do:
+
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?
  
$ splash.py merge rhine/int
+
Possible answers:
  # test
+
* A. outside the tree is a pain - it's too removed from the code
$ splash.py unmerge rhine/int
+
* 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.
  
If you change dependencies in the Splashfile, such as adding
+
Does splash modify the Splashfile itself when you execute commands?
'my-feature' to the rhine/int deps, you'll need to execute:
 
  
$ splash rebuild rhine/int
+
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?
  
=== WIP documentation ===
+
How is splash similar or different to stacked git?
  
== Questions ==
+
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?
  
* Q: what is the 'splash.remote' needed by splash?
+
How do I set up a new splash tree?
* Q:
 
  
 
== Bugs ==
 
== Bugs ==
  
=== Splash can not show help (-h) in some situations ===
+
=== Splash can not show help (-h,--help,help) in some situations ===
  
 
Doing 'splash.py -h' in a repostiroy without a splash.remote results in:
 
Doing 'splash.py -h' in a repostiroy without a splash.remote results in:
Line 135: Line 175:
 
subprocess.CalledProcessError: Command '['git', 'rev-parse', '--git-dir']' returned non-zero exit status 128
 
subprocess.CalledProcessError: Command '['git', 'rev-parse', '--git-dir']' returned non-zero exit status 128
 
</pre>
 
</pre>
 +
 +
=== error message when using invalid command is confusing ===
 +
'foo' is not a valid splash sub-command.
 +
<pre>
 +
$ splash foo
 +
'config' section or command line must specify branch
 +
</pre>
 +
 +
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'.

Latest revision as of 06:43, 25 January 2014

Splash is a tool to manage patch series and dependencies between them in git. A 'splash' is defined by a set of branches that can be applied to (integrated into) a working branch of a source tree. The 'Splashfile' defines all of the '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.

It has similarities to quilt and stacked-git. But both of those only support a single series of patches. Splash supports a hierarchy of nested branches, each containing multiple sets of commits.

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.

In order to use splash, you have to first fetch the splashes.

$ splash.py fetch <splash_name>

Splash workflow

As a general rule, working with splash works like so:

$ splash.py fetch <splash_name>
  # edit Splashfile to add splash 'my-feature'
$ splash.py start my-feature
  # make / add commits
$ git update-ref refs/splash/my-feature HEAD
$ splash.py push my-feature

At any point you can also do:

$ splash.py merge rhine/int
  # test
$ splash.py unmerge rhine/int

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:

$ splash.py fetch # or fetch-all or fetchall; fetches all splashes

or

$ splash.py fetch rhine/int # for all splashes rhine/int depends on

or

 $ git fetch origin $(for ref in `sed -n '/^ref/x;s/ref\s*=\s*//p' Splashfile`; do
        echo "$ref:refs/heads/${ref:12}"; done)  # poor man's splash

If you do it with splash, they won't be branches, but instead refs in refs/splash/<splash-name>. If you want to turn these into branches, try:

$ for splash in `find .git/refs/splash/ -type f`; do
     git update-ref refs/heads/splash/${splash:17} ${splash:5}; done

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.

This replaced my retrieval of a topic branch:

$ git fetch origin refs/topics/<developer_name>/<topic_branch_name>
$ git checkout -b <local_branch_name> FETCH_HEAD

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:

No upstream specified
Please run `git config --local --add splash.remote <remote>`

If you run this outside of a git directory, you get the following:

$ splash
fatal: Not a git repository (or any parent up to mount point /home)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
Traceback (most recent call last):
  File "/home/CORPUSERS/10102229/bin/splash", line 436, in <module>
    gitconfig = GitConfig()
  File "/home/CORPUSERS/10102229/bin/splash", line 71, in __init__
    raise subprocess.CalledProcessError(repo.returncode, cmd, output=out)
subprocess.CalledProcessError: Command '['git', 'rev-parse', '--git-dir']' returned non-zero exit status 128

error message when using invalid command is confusing

'foo' is not a valid splash sub-command.

$ splash foo
'config' section or command line must specify branch

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'.