Docs/update husky docs to make them more intuitive

[doublethefish]

Initially, I found it quite hard to understand the husky docs, so I thought I would capture my learning and attempt to make the docs easier to follow. Mainly because I think I will be using husky a lot in the future and I have the memory of a goldfish.

I've clarified:

• husky requires git 2.9+ because of core.hooksPath support
• what prepare does and why
• what the differences between husky-init and husky install are
• how to manage hooks code
• grouped and added some more comprehensive examples
• added some notes on how to avoid gotchas (in addition to the troubleshooting section)

I've also conformed the 3 readmes, copying the quick-setup sections from the main docs:

• ./README.md
• ./.github/README.md

Finally, I've also added an example prepare-commit-msg hook with an external script, as requested by jcollum-nutrien

[devinrhode2]

This looks like really great stuff! I just had a quick glance at files changed

There are some conflicts, could you rebase into latest master "git pull origin master --rebase" to resolve conflicts? You can consult "git rebase --show-current-patch" to see what a conflicting commit was intending to do

[wsuwt]

Thank you! I find this version of documentation a lot less confusing.

[doublethefish]

Done.

The conflict was with the instruction to auto-install hooks on npm install: npm set-script prepare "husky install" -> npm pkg set scripts.prepare="husky install"

I've replaced all three places that describe that step.

[blwinters]

@doublethefish It looks like the example for prepare-commit-msg is no longer in this PR. Maybe it was accidentally removed during the rebase?

[doublethefish]

I removed it. Whilst trying to understand the (very poorly structured) feedback I found a few issues that required some more work, so because it polluted the main purpose of the PR I pulled it for now - I assumed it was slowing reviews.

I am fairly sure I found a bug in how husky handles bash expansions that would need to be fixed before adding an example. But I'd need to dig into it a produce a decent enough bug report.

Once this gets merged I'll open Issues/PRs for both the bug(s?) and add an example or two, when I get time.

[blwinters]

I see. I was able to find a link to your original example that got me unblocked with this, so thanks for that. I'm sure others would be grateful for this to be better explained in the documentation.

[blwinters]

You might also consider including checks for "special" commits in your example, like these:

COMMIT_SOURCE=$2

# ignore merge commits
if [ "${COMMIT_SOURCE}" = merge ]; then
    exit 0
fi

# ignore fixup! and squash! commits
if cat "$1" | grep -E -i "^(fixup|squash)!" > /dev/null; then
    exit 0
fi

[doublethefish]

That's a good suggestion.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[paescuj]

I wonder if two different README.md files are really necessary... Couldn't we just use the .github/README.md one? I assume it has been set-up that way because of rendering issues on npmjs.com, but I feel like this should no longer be a problem these days. Also, we could just leave out the instructions in the README altogether and link to the documentation instead. WDYT?

[doublethefish]

@paescuj couldn't agree more but the idea was rejected here #1166 and here #1167.

Personally, I have decided to stop contributing to this project.

[paescuj]

Oh, I see. That is really a pity!