Support fresh repositories (with no commits)

[timwis]

At the moment GitSheets has to be run against an initialised git directory with at least one commit made, so we have a bunch of git commit -m 'init' --allow-empty in tests/docs/etc. I believe the reason it requires at least one commit is that hologit/Repo's getFromEnvironment static method is running git rev-parse --verify HEAD (see here).

According to @themightychris:

There's a wrapper for that in Git or Hologit that provides for just returning null instead of throwing an exception for cases where potential nonexistense is anticipated
We should use that call instead, and I'm leaning towards it being best to generate an initialization commit rather than just start a new chain from an import with no parent
Link. use the Repo class to "open" the repo ^ that will let you instantiate it with a selected ref. instead of hardcoding HEAD everywhere.

To which I replied:

in other words Repo.createFromEnvironment({ ref: await resolveRef() }) ?
won't it resolve to null and we're in the same situation?

[themightychris]

Well we won't get an exception because there's no HEAD, we'll get a null head. The we just need to skip passing a parent commit to commit-tree if we don't have one and the first commit will be a root commit

[themightychris]

Re calling createFromEnvironment, we can omit ref and let it default to HEAD, and that gets you the same behavior as scripting the git CLI: if you run any commands that need to default to your current environmental head and there is none yet it's an exception. We need to handle the case of an empty HEAD as a normal state in the places where it can happen, and not call commands that won't work without one

[themightychris]

Oh also, this example is kind of circular/backwards:

Repo.createFromEnvironment({ ref: await resolveRef() })

You wouldn't do this, createFromEnvironment taking a ref is just a way for you to set a session-level default for commands to use. It's like the USE statement in SQL. You'd normally just let this default to HEAD which uses git's on-disk stateful "current branch" pointer (it's a symbolic ref that just links to whatever ref you have checked out--it IS the state of having something checked out). Passing ref when you create a Repo instance let's you "open" a different ref.

If you pass a commit hash to it, like this code would, that's like checking out a commit directly and getting a detached head. You can query it just fine, but it's never gonna move forward to any new commits

What you want to do is only pass a named ref to createFromEnvironment IF at the session/command level the user has specified to "open" a branch/ref to work on

Then, use repo.resolveRef() if you need to get the hash of the current commit that repo.ref resolves to (resolveRef doesn't get you a ref, it takes one and gets you its current hash value). But the result of resolveRef with no ref passed is just a static capture of what most operation will use as their subject by default, so you don't generally need to be grabbing passing around the hash of the current env unless you want to log it

[timwis]

Perhaps I'm misunderstanding, but I believe what your describing does not work as intended, and throws the error I'm referring to.

Steps to reproduce:

1. git init tmp
2. GIT_DIR=tmp/.git node
3. const { Repo } = require('hologit/lib');
4. Repo.getFromEnvironment().then(console.log).catch(console.error);

Throws error:

Command failed: git rev-parse --verify HEAD
fatal: Needed a single revision

I believe this is because Repo's createFromEnvironment method executes the above rev-parse command. I've trid calling the method with the ref arg set to null, '', and 'master', which is reflected in the command that's logged, but they all throw the same error.