Add option for shallow clones (--depth N)

[shwaka]

This PR adds option for shallow clone (--depth N), only for packages whose versions are not locked.

• This PR resolves Add option for shallow clones #2 partially.
• This PR is based on Support for git clone --depth #284.
  I was thinking whether to continue Support for git clone --depth #284, but I decided to create a new PR because Support for git clone --depth #284 is too old to merge today.

I really want an option for shallow clones, but, unfortunately, it is difficult to treat version locking as discussed in #2. So I implemented an option for shallow clones only for packages whose versions are not locked.
Of cource, I know this implementation is far from complete, but it is useful at least for me (and hopefully some of other people).

I welcome any kind of comments, including disagreement.

Usage

Note that, if you add nothing in your init.el, then this PR does nothing.

;; Change the default value of the option
(setq straight-vc-git-default-clone-depth 1)

;; Change the option for a single package, say `lsp-mode'
(straight-register-package
 '(lsp-mode :type git :host github
            :repo "emacs-lsp/lsp-mode"
            :depth full))
(straight-use-package 'lsp-mode)

The value of the option :depth or straight-vc-git-default-clone-depth can be the following:

• the symbol full, which means clone without --depth option
  (This is the defualt value)
• an integer N, which means clone with the option --depth N

Implementation

This PR changes the function straight-vc-git-clone.

• If the argument commit is non-nil (some SHA-1 hash), then this PR changes nothing. Hence use git clone as before.
• If the argument commit is nil, then use git clone with the option --depth.

This works well even if some branch is specified in recipe, since the option --branch is added to git clone.

Fallback for dumb http protocol

As far as I know, dumb http protocol does not support --depth option. Hence, for a packages provided by dumb http protocol, the command git clone --depth fails. As a fallback, I wrote the error-handler in condition-case in straight-vc-git--clone-internal.
Of cource, straight.el will send requests twice in this case, so it will be slower than before. But I ignored this performance issue, because very few packages are provided by dumb http protocol, I believe.
(I found only one package, paredit, using dumb http protocol among 90 packages which I use)

[raxod502]

This looks very nice, thanks!

I'd be happy to merge it if you update the documentation.

[raxod502]

What does including --branch here do?

[shwaka]

--branch was added here to make :branch in a recipe work well. For example, I'm using the following code in my init.el.

(straight-register-package '(all-the-icons-dired :type git
                                                 :host github
                                                 :repo "shwaka/all-the-icons-dired"
                                                 :branch "fixedwidth"))

If we don't add --branch, then straight.el will raise a warning such as

Warning (straight): Could not check out branch "fixedwidth" of repository "all-the-icons-dired"

since we don't have the branch fixedwidth in the local repository because of the shallow clone.

[raxod502]

That is a very good point. Thank you for the clear explanation; you have obviously done the right thing in this code.

[shwaka]

Thank you for your review and I'm very happy to hear that!

Of cource I will update the documentation, but I'm not sure where to write it. I think we need the documentation for

• :depth option for recipes and
• straight-vc-git-default-clone-depth.

The first one should be written in the section "Git backend" in README.md, right? How about the second one? Maybe the section "Miscellaneous"?

[raxod502]

I would say that both the keyword and the user option can be documented in the "Git backend" section of the README. There is a list ("You can customize the following user options: ...") in that section, and straight-vc-git-default-clone-depth would fit perfectly there.

[shwaka]

Sorry, I missed that section. I wrote both there, following your recommendation.

[shwaka]

Additionally I pushed some commits to make Travis CI successful.

Could you please check if it can be merged?

[raxod502]

It looks wonderful. Thank you for your help! 🎉