Documentation on Hooks

[nfarrar]

The docs/hooks page has a list of hooks with some documentation on some of the hooks that are available. Is it possible to add some documentation on those that don't already have it?

Specifically, I'm working with the pre-upgrade hook right now for using it to configure sparse-checkouts as discussed in this thread. I was trying to identify exactly when this hook is run and why this hook was chosen over any of the others by @vdemeester & @jwhitley. The documentation didn't provide any indication of why this was the choice.

[jwhitley]

Good point. I ended up checking out the vcsh source, as there's a number of useful, undocumented hooks and it's not entirely clear at first blush which hooks get called for which commands. E.g. pre-command/post-command get wrapped around every vcsh command invocation. vcsh clone calls (at least):

clone():
  pre-clone
    init():
      pre-init
      upgrade():
        pre-upgrade
        post-upgrade
      post-init
  pre-merge
  post-merge
  post-clone
  post-clone-retired

and so on.

I'll propose a documentation structure: First, a directory that lists all hooks, with a short text description of what each hook phase does (e.g. "init" vs. "upgrade"). Second, a per-command directory, similar to the above, that lists each hook called in-order for that command. Most commands are far simpler than clone, so this shouldn't be too bad. A set of dummy hooks (e.g. echo "doc: pre-merge hook") could be created to help produce the listing.

[nfarrar]

That would be helpful. :) I just did a little testing and noticed that the pre-upgrade hooks don't run against an existing repository when fetching & merging changes from a remote.

This is probably ok for most situations, but if you've already cloned the repository, then add one of the ignored files (from a git checkout) and update the repository via vcsh, the hook never executes, so sparse-checkout is never configured and you end up with the files $HOME.

In most situations this is easily resolved by deleting & recloning the repository. However if your hooks are stored in a repository (i.e. mine are sitting in my vcsh branch), then you end up with a chicken-egg type scenario.

I see a couple ways to resolve this:

From @vdemeester's vcsh-home repository: use a bootstrap script to write the hooks from a script.

I prefer to have them stored in the repository as files, rather than being written by a script (seems a little more straight-forward to me), so rather than writing them from a script, use a bootstrap script to curl them into place, then when cloning the repository, a post-merge-unclobber script to gracefully replace them - however this leaves the scenario (unless a post-delete hook is added) where deleting the repository leaves the system in a state where the hooks are no longer present and sparse-checkout won't be configured. It looks like that scenario is similar to what your doing (@jwhitley in your bootstrap script).

I think the answer I'm looking for may be to attempt to use one of the other hooks that runs on more than just clone events, and configures sparse-checkout whenever it's not present (so it'll be updated even on pull) and then update the work tree as necessary (git read-tree -mu HEAD) to have those files removed from $HOME automatically.

[jwhitley]

Note that vcsh upgrade is a separate, explicit command. It's not automatically run on vcsh pull, but you can still keep the hooks in the repo. The simplest workflow is to use two steps when an upgrade is required, which is what I do since it's so infrequent:

# get new changes
vcsh pull
# run any vcsh upgrade hooks
vcsh upgrade

Note that you can add multiple symlinks in ~/.config/vcsh/hooks-enabled to your upgrade script(s). E.g. I keep the actual scripts in ~/.config/vcsh/hooks-available. Some of these are symlinked to run under multiple hooks under the hooks-enabled directory. If you always want to run your extra upgrade steps on every vcsh pull, you might link both pre-upgrade.00-foo-bar and post-pull.00-foo-bar to catch both initial repo setup and pulling new changes. I don't bother with this since needing to upgrade is a pretty rare operation for me.

However, I do use that to ensure my repo settings are in place during the bootstrap run. (This is my way of avoiding making these settings in the bootstrap script, which I also wasn't keen on.) If you check out my vcsh hook symlinks you'll note that I hook some scripts to both mr.post-clone and pre-upgrade. The mr.post-clone runs ensure my settings (sparse checkout and rebase-on-pull) are in place on the "root" vcsh repository (my vcsh-root repo, named mr locally for vcsh). That's necessary because the update hooks don't exist yet when the initial vcsh clone happens. These same hooks are also linked to pre-upgrade to cover the rest of the regular repositories.

[nfarrar]

Sorry for late response. Thank you @jwhitley for that information. When I was looking into this, I hadn't played with the hooks much yet. That info above got me started, and since I've been able to adapt and use these pretty extensively to do what I want.

@RichiH The information in this thread was really helpful to build some starting use cases, develop a solid understanding of how vcsh/git hooks work, and then go off on my own and do exactly what I want. You might consider adding some of it to the documentation (as use-case examples, perhaps)?.

[jwhitley]

Motion seconded. @RichiH I'll pitch in to help get some better docs on this stuff in place. What would help me get that done is agreement as to where to put stuff. I see two parts:

1. Basic documentation around hooks. This probably wants to be directly in the man pages.
2. A vcsh cookbook, where user-guide content can go. This also becomes a nice place to consolidate the best ideas from the mailing list.

For (1), I can submit a PR vs the man pages with an expansion to the HOOK SYSTEM section. (Yay, I see it uses ronn so I don't have to nroff. ❤️)

For (2), I see this as "here's how I do X with vcsh" topics, where users can write up the ways they use vcsh to solve problems. For hosting, the wiki on this repo seems a likely candidate.

Another low-administration alternative would be to use GitHub pages, either directly against this repo (RichiH.github.io/vcsh) or possibly as the user-level Pages site on a vcsh organization (vcsh.github.io). That way it's still fairly straightforward to contribute to, and it's easy for the content to be cloned, independently generated via Jekyll, etc.

[RichiH]

@jwhitley Yes, please!

Feel free to extend the hooks with basic stuff. The rest should go into doc/hooks, but you are more than welcome to rename to doc/hooks.md if you want more capabilities.

As to GitHub pages: All documentation must live in the main repo, but I have been thinking about using https://github.com/spf13/hugo to sync doc/ onto a GitHub page anyway. If possible, keeping that in mind while (re)writing docs would be appreciated.

[jwhitley]

Great, I'll start on the man page PR first.

Are there particular feature(s) that have caught your eye from Hugo? I'm passing familiar with it, but can't make a bullet list of Jekyll vs. Hugo's details off the top of my head.

[RichiH]

Hugo seems more modern and I am being fascinated with go at the moment. Fwiw, I come from ikiwiki ;) Richard Sent by mobile; excuse my brevity.

[jwhitley]

Righto. I'll setup for Hugo then. I'm interested in giving it a go as well (ooh, pun!), and I'll provide a little feedback on the author workflow. With most of these static generators, it's pretty easy to flip from one to another with HTML+Markdown content, so it's not like there's any big lock-in to a decision.