RFC: Initial git save format

[Linus Torvalds]

On Thu, Mar 6, 2014 at 1:54 PM, Dirk Hohndel <dirk at hohndel.org> wrote:
>
> how do you intend the actual UI to work?
> Ideally this would be a "no user interaction UI" in most cases. I don't
> want divers to have to wonder what we might mean by "branch" and other
> strange terminology...

So my expectation is that we'd want to do:

 - in the preferences under "Default Dive file", have some way to pick
a git repository and a branch name. Then we could create it if it
doesn't exist.

   Creating the git repo is trivial ("git_repository_init()"), but
right now we just have the standard file chooser dialog, which
obviously does not have the interfaces to specify that we want to do a
git repo and a write a branch.

 - The same issue is true under "Save As". Again, we use the standard
Qt file picker, and it's the exact same issue.

So basically, if it's possible to extend the normal file save dialog
to have a checkmark for "use git repository" and a text field for the
branch name, that would probably trivially do it.

>> The file format for each dive is fairly sane, and might not need much
>> changing (it looks a lot like the current XML, except it's a
>> file-per-dive, and it lacks all the crazy XML syntax). But I don't
>> save the dive trip notes etc right now at all, so the trip data itself
>> isn't there, and I am pretty sure that I want to do a deeper directory
>> hierarchy with at the very least each year getting its own
>> subdirectory.
>
> what happens to dive trips that straddle New Year's Eve? The date of the
> first dive determines the location?

Yes, exactly as if a dive straddles the day or year - the dive will be
shown on the day it starts ;)

> Can you make it add the subsurface version number to the commit message?

Yes, I should do that. I also should make the authorship information
match the current user, but the libgit2 function to do that is another
version-dependent one (and this time I was aware of the version
dependency, so I avoided it).

> What's your realistic expectation how long it will take for this to
> shake out? I had made the assumption that this would go into 4.2, not
> 4.1, so maybe I should put it in a branch for now?

I'll need to flesh out the writing part a bit (improved paths, add the
trip info I skipped entirely, etc). I'll do that tomorrow.

The reading part isn't really any harder, I expect to do that over the weekend.

The directory layout and file format might change a bit, but assuming
I get the parsing done, I'd expect next week to be close to a final
format. I need to get this done before next kernel merge window.

The UI parts I'm not really planning to touch, so..

> Since this is not a checked out format, I think this makes a lot of
> sense. I assume that would mean that there is a "special" file for the
> dive data and then individual files for each DC that are identified by
> the DC deviceid?

They'd just be "dc0..dcX", since there is no guarantee that we have a
unique device ID. The trips are named "trip001...tripXYZ" for the same
reason. The dc/trip data is then inside the file.

Also, note that while *subsurface* doesn't check the branch out, there
is nothing inherently wrong with checking the files out using git. In
fact, for the whole "let's merge" thing, that would be how it's done,
since that's how git merges things. And it would be how you'd edit
things if you do it outside of subsurface (ie there might be tools to
convert to other formats that check out the git state and then convert
from the filesystem).

So you *can* use it as a checked-out tree, it just wouldn't be
anything subsurface cares about. For subsurface, you would likely
mostly use a so-called "bare" git repo (and that's what I'd do by
default for the "create repo" case when creating a repository from
within subsurface, see above about the lack of UI for that, though)

> I would definitely want one "unit" per dive. So either one file or one
> directory by itself. Let's not have the "day" be a special unit that
> contains more than one dive (without sub-structure)...

The "day" part would at most be a directory that then has files in it.
But I suspect I'll at most want to have "year+month" as a directory
structure, so that you can easily find trips and dives by date.

> Some comments for the others who haven't been part of our
> conversation... correct me where I'm misremembering things
>
> - this is intended as our internal format
> - we continue to allow to save to XML (for export, transport, etc)
> - we can use all the neat networking capabilities of git - so it's easy
> to then put the data store on a server and use it from different clients
> - this trivially gives us backup and versioning, but that of course
> requires a sane UI to deal with it (that alone makes this 4.2 material)
> - this does not by itself solve the problem of merging multiple edits of
> the SAME dive. But it trivially deals with edits (and adding) of
> different dives independently on different machines

Correct. And the git file layout is meant to make it easy to do the
merging across machines.

                 Linus