Difference between revisions of "Splash"
(add more splash info) |
(fix more stuff) |
||
Line 13: | Line 13: | ||
[ FIXTHIS - put list of commands here ] | [ FIXTHIS - put list of commands 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 | ||
+ | * -l or --list - list splashes and exit | ||
+ | * -b or --base - specify base splash | ||
+ | * -v or --verbose - be verbose | ||
+ | |||
== Splash setup == | == Splash setup == | ||
Line 48: | Line 65: | ||
the following ways: | the following ways: | ||
− | + | * $ splash.py fetch # or fetch-all or fetchall; fetches all splashes | |
− | + | * $ splash.py fetch rhine/int # for all splashes rhine/int depends on | |
− | + | * $ 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 56: | Line 73: | ||
refs/splash/<splash-name>. If you want to turn these into branches, try: | refs/splash/<splash-name>. If you want to turn these into branches, try: | ||
− | $ for splash in `find .git/refs/splash/ -type f`; do | + | $ for splash in `find .git/refs/splash/ -type f`; do |
git update-ref refs/heads/splash/${splash:17} ${splash:5}; done | git update-ref refs/heads/splash/${splash:17} ${splash:5}; done | ||
Line 71: | Line 88: | ||
As a general rule, working with splash works like so: | As a general rule, working with splash works like so: | ||
− | $ splash.py fetch | + | $ splash.py fetch <splash_name> |
# edit Splashfile to add splash 'my-feature' | # edit Splashfile to add splash 'my-feature' | ||
− | $ splash.py start my-feature | + | $ splash.py start my-feature |
# make / add commits | # make / add commits | ||
− | $ git update-ref refs/splash/my-feature HEAD | + | $ git update-ref refs/splash/my-feature HEAD |
− | $ splash.py push my-feature | + | $ splash.py push my-feature |
At any point you can also do: | At any point you can also do: | ||
− | $ splash.py merge rhine/int | + | $ splash.py merge rhine/int |
# test | # test | ||
− | $ splash.py unmerge rhine/int | + | $ splash.py unmerge rhine/int |
If you change dependencies in the Splashfile, such as adding | If you change dependencies in the Splashfile, such as adding | ||
'my-feature' to the rhine/int deps, you'll need to execute: | 'my-feature' to the rhine/int deps, you'll need to execute: | ||
− | $ splash rebuild rhine/int | + | $ splash rebuild rhine/int |
Revision as of 16:04, 22 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.
Contents
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 - put list of commands 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
- -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>
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
- $ splash.py fetch rhine/int # for all splashes rhine/int depends on
- $ 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/<dev_name>/<splash_name> $ git checkout -b <local_branch_name> FETCH_HEAD
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
WIP documentation
Questions
- Q: what is the 'splash.remote' needed by splash?
- Q:
Bugs
Splash can not show help (-h) 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