Update upgrade/outdated documentation

[vladshablinsky]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew tests with your changes locally?

---

Document new --fetch-HEAD flag for outdated and upgrade commands.

[MikeMcQuaid]

@vladshablinsky Current text reads a bit weird. How about (assuming it's accurate):

If `--fetch-HEAD` is passed, fetch the upstream repository to detect if the HEAD
installation of the formula is outdated. Otherwise, the repository's HEAD will be
checked for updates when a new stable or devel version has been released.

[MikeMcQuaid]

Also, how long does this operation take on e.g. a standard GitHub repo?

[vladshablinsky]

How about (assuming it's accurate)

Looks good.

[vladshablinsky]

how long does this operation take on e.g. a standard GitHub repo?

@MikeMcQuaid, I will test, but shouldn't be too time-consuming for GitHubGitDownloadStrategy. However, for GitDownloadStrategy we need to fetch the repo, so it takes some time. How do I understand whether results are OK or not OK when I do some benchmarks?

[MikeMcQuaid]

Just post them here 😀. I think we could do it automatically for GitHub, then?

[xu-cheng]

I think we could do it automatically for GitHub, then?

I would avoid it otherwise we may get formula tagged as outdated for a popular repo too often whenever we run brew upgrade/outdated. We need a flag to control the behaviors, whether you want prompt update or not.

Besides the time is still relative consuming:

$ time brew outdated
brew outdated  0.59s user 0.14s system 79% cpu 0.921 total
$ time brew outdated --fetch-HEAD
neovim/neovim/neovim (HEAD-4dc4efc) < HEAD-abb0928dfbf71d5358b56e888db9ed8ff66d8933
brew outdated --fetch-HEAD  0.54s user 0.10s system 13% cpu 4.918 total