newbie: "fake" README for remote of a `vcsh` repo?

[Vincent Demeester]

Re,

Tom Roche writes:

> Vincent Demeester Tue Feb 10 19:30:08 CET 2015 (rearranged) [1]
>> The downsides of this approach is that you have to create/edit the 
>> README "outside" ~/ and vcsh (in another working copy).
> 
> That does *not* sound like a problem to me. In fact, (IIUC) I 
> originally proposed doing something like that:
> 
> TomRoche 9 Feb 2015 ~1730 EST [2]
>>> I thought I could do something like
> 
>>>   $ mkdir -p ~/info/software/vcsh/fake_repositories/vcsh-bash-fake/
>>>   # edit 
>>> ~/info/software/vcsh/fake_repositories/vcsh-bash-fake/README.rst
>>>   $ pushd ~/info/software/vcsh/fake_repositories/vcsh-bash-fake/
>>>   $ ls -al # check to see that it indeed is there
>>>   $ vcsh vcsh-bash add README.rst
>>>   $ vcsh vcsh-bash status | | head -n 20
>>>   ...
>>>   > Changes to be committed:
>>>   ...
>>>   >       new file:   README.rst
> 
>>> but vcsh is too smart for that:

Richard already commented on thi (kind of) ; it's not really part of the
use cases of either git or vcsh.

>>>   $ vcsh vcsh-bash commit -m 'add a README for the remote'
>>>   > [master e4d4230] add a README for the remote
>>>   >  1 file changed, 6 insertions(+)
>>>   >  create mode 100644 
>>> info/software/vcsh/fake_repositories/vcsh-bash-fake/README.rst
> 
>> If you setup a vcsh hook at the 'correct' time (i.e. between the init 
>> and the first fetch)
>> that will set-up the repository with sparseCheckout to ignore the 
>> README(s),
>> you won't even have to think about seeing README.rst in git status and 
>> git diff.
> 
> OK, but note the "newbie" in the Subject line :-) I'm a beginner-level
> `git` user and a totally-novice-level `vcsh` user. So can you either
> explain how to setup the `vcsh` hook, or point me to doc? (I'm good
> with RTFM if I know where to find them.)

I didn't really notice the "newbie" in the subject line (I've read it on
my phone) and didn't thought it was a newbie question (and I still not
:P).

Anyway, if you're looking for help, here we go.
As we said earlier, vcsh support some kind of hook, there is multiple
"place"[1] where you can add yours, that's what we're going to do. We're
also gonna use a pretty cool feature of git, which is called
sparseCheckout[2].

Let's define which hook we want to use ; to do that, let's see how vcsh
clones a repository (or init it). When you call clone, it does :

1. run hook pre-clone
2. call init
2.1. run hook pre-init
2.2. create the right folder and ``cd`` in it
2.3. init it (git init..)
2.4. call upgrade
2.4.1. run hook pre-upgrade
2.4.2. configure stuff (core.bare to false, core.worktree, vcsh.vcsh,
..)
2.4.3. call use
2.4.4. run hook-post-upgrade
2.5. run hook post-init
3. configure stuff (branches, verify if the remote is empty or not, ..)
4. fetching from the remote
5. verifying if there will be no conflicts (files that are present in
$HOME that are not in the current index but are in the remote one).
6. merging it
7. […]

We want to run a command *and* set up a file before merging it (I tend
to think I want to do it as early as possible). The hooks that could
work are after the 2.3 init phase and before merging it, so it's one of:
- pre-upgrade
- post-upgrade
- post-init

I tend to use pre-upgrade but I think the best one might be post-init
:-P.

vcsh looks for executable file as hooks in
$XDG_CONFIG_HOME/vcsh/hooks-enabled (usually $XDG_CONFIG_HOME is
$HOME/config so ~/.config/vcsh/hooks-enabled). Let's create an
executable script : ~/.config/vcsh/hooks-enabled/setUpSparseCheckout.sh
with the following content.

#!/bin/sh
if ! test "$(git config core.sparseCheckout)" = "true"; then
    # Enable sparseCheckout for the repository
    git config core.sparseCheckout true
    # And write the sparseCheckout configuration where it's needed
    cat >> $GIT_DIR/info/sparse-checkout << EOF
# vcsh automatic sparse-checkout configuration
*
!README
!README.rst
!README.md
!README.org
EOF
fi

A little explanation about the $GIT_DIR/info/sparse-checkout, as it is
documented : sparseCheckout is usually used to specify what files are in
; but in our case we want the opposite, specify what files are *not* in.
That's why we are first writing "*", meaning "includes all by default",
and then add lines like "!README.rst", meaning "do not checkout this
one".

Because you can set multiple hooks on vcsh, you could split the previous
one in several pieces (one for git config core.sparseCheckout, one for
the actual file, ..). That's what I'm doing on my bootstrap script[3].

I hope I helped and that it was clear enough to be understood, don't
hesitate to tell me if something is still not clear ;-). Git have also
hooks, so you could play around it too but I think it's would be too
much :P.

(Seems like I have a misconfiguration on my laptop for mails, so I'm
hopefully not reposting this, sorry if I am -_-)


[1]: https://github.com/RichiH/vcsh/blob/master/doc/hooks
[2]: https://schacon.github.io/git/git-read-tree.html#_sparse_checkout
[3]: 
https://github.com/vdemeester/vcsh-home/blob/bootstrap/bootstrap.sh#L73:L127
-- 
Vincent Demeester