Merge pull request #14023 from EricFromCanada/docs-add-common-issue

Docs: mention "path not in the working tree" error in Common Issues

docs/Adding-Software-to-Homebrew.md

@@ -2,7 +2,7 @@
 
 Is your favorite software missing from Homebrew? Then you're the perfect person to resolve this problem.
 
-If you want to add software that is either closed source or a GUI-only program, you will want to follow the guide for [Casks](#casks). Otherwise follow the guide for [Formulae](#formulae). See also: [Homebrew Terminology](Formula-Cookbook.md#homebrew-terminology)
+If you want to add software that is either closed source or a GUI-only program, you will want to follow the guide for [Casks](#casks). Otherwise follow the guide for [Formulae](#formulae) (see also: [Homebrew Terminology](Formula-Cookbook.md#homebrew-terminology)).
 
 Before you start, please check the open pull requests for [Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/pulls) or [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask/pulls) to make sure no one else beat you to the punch.
 
@@ -34,7 +34,7 @@ If you're stuck, ask for help on GitHub or [Homebrew/discussions](https://github
 
 ### Submitting the formula
 
-You're finally ready to submit your formula to the [homebrew-core](https://github.com/Homebrew/homebrew-core/) repository. If you haven't done this before, you can refer to the [How to Open a Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation for help. Maintainers will review the pull request and provide feedback about any areas that need to be addressed before the formula can be added to Homebrew.
+You're finally ready to submit your formula to the [homebrew-core](https://github.com/Homebrew/homebrew-core) repository. If you haven't done this before, you can refer to the [How to Open a Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation for help. Maintainers will review the pull request and provide feedback about any areas that need to be addressed before the formula can be added to Homebrew.
 
 If you've made it this far, congratulations on submitting a Homebrew formula! We appreciate the hard work you put into this and you can take satisfaction in knowing that your work may benefit other Homebrew users as well.
 
@@ -166,7 +166,7 @@ Fill in the following stanzas for your cask:
 | ------------------ | ----------- |
 | `version`          | application version
 | `sha256`           | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be suppressed by using the special value `:no_check`. (see [`sha256` Stanza Details](Cask-Cookbook.md#stanza-sha256))
-| `url`              | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.<br />A [`verified` parameter](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified) must be added if the hostnames in the `url` and `homepage` stanzas differ. [Block syntax](Cask-Cookbook.md#using-a-block-to-defer-code-execution) is available for URLs that change on every visit
+| `url`              | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.<br />A [`verified` parameter](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified) must be added if the hostnames in the `url` and `homepage` stanzas differ. [Block syntax](Cask-Cookbook.md#using-a-block-to-defer-code-execution) is available for URLs that change on every visit.
 | `name`             | the full and proper name defined by the vendor, and any useful alternate names (see [`name` Stanza Details](Cask-Cookbook.md#stanza-name))
 | `desc`             | one-line description of the software (see [`desc` Stanza Details](Cask-Cookbook.md#stanza-desc))
 | `homepage`         | application homepage; used for the `brew home` command
@@ -179,7 +179,7 @@ Other commonly used stanzas are:
 | `livecheck`        | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck))
 | `pkg`              | relative path to a `.pkg` file containing the distribution (see [`pkg` Stanza Details](Cask-Cookbook.md#stanza-pkg))
 | `caveats`          | a string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats))
-| `uninstall`        | procedures to uninstall a cask. Optional unless the `pkg` stanza is used. (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall))
+| `uninstall`        | procedures to uninstall a cask; optional unless the `pkg` stanza is used (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall))
 | `zap`              | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap))
 
 Additional [`artifact` stanzas](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required) may be needed for special use cases. Even more special-use stanzas are listed at [Optional Stanzas](Cask-Cookbook.md#optional-stanzas).

docs/Common-Issues.md

@@ -99,6 +99,23 @@ Don't follow the advice here but fix by using
 `Language::Python.setup_install_args` in the formula as described in
 [Python for Formula Authors](Python-for-Formula-Authors.md).
 
+## Installation fails with "unknown revision or path not in the working tree"
+
+When installing Homebrew, if the initial download fails with something like:
+
+    error: Not a valid ref: refs/remotes/origin/master
+    fatal: ambiguous argument 'refs/remotes/origin/master': unknown revision or path not in the working tree.
+    Use '--' to separate paths from revisions, like this:
+    'git <command> [<revision>...] -- [<file>...]'
+
+Or:
+
+    fatal: the remote end hung up unexpectedly
+    fatal: early EOF
+    fatal: index-pack failed
+
+This is an issue in the connection between your machine and GitHub, rather than a bug in Homebrew itself. See this [discussion topic](https://github.com/orgs/Homebrew/discussions/666) for a number of solutions others have found, such as using a wired connection or a VPN, or disabling network monitoring tools.
+
 ## Upgrading macOS
 
 Upgrading macOS can cause errors like the following:
@@ -126,8 +143,8 @@ If, however, you do not have a `.curlrc` or removing it did not work, let’s se
 
 The cask is outdated. Let’s fix it:
 
-1. Look around the app’s website and find out what the latest version is. It will likely be expressed in the URL used to download it.
+1. Look around the app’s website and find out what the latest version is. It may be expressed in the URL used to download it.
-2. Take a look at the cask’s version (`brew cat <cask_name>`) and verify it is indeed outdated. If the app’s version is `:latest`, it means the `url` itself is outdated. It will need to be changed to the new one.
+2. Take a look at the cask’s version (`brew info <cask_name>`) and verify it is indeed outdated. If the app’s version is `:latest`, it means the `url` itself is outdated. It will need to be changed to the new one.
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
@@ -135,7 +152,7 @@ Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEA
 
 The issue isn’t in any way related to Homebrew Cask, but with the vendor or your connection.
 
-Start by diagnosing your connection (try to download other casks, go around the web). If the problem is with your connection, try a website like [Ask Different](https://apple.stackexchange.com/) to ask for advice.
+Start by diagnosing your connection (try to download other casks, or browse around the web). If the problem is with your connection, try a website like [Ask Different](https://apple.stackexchange.com/) to ask for advice.
 
 If you’re sure the issue is not with your connection, contact the app’s vendor and let them know their link is down, so they can fix it.
 
@@ -145,46 +162,42 @@ If you’re sure the issue is not with your connection, contact the app’s vend
 
 First, check if the problem was with your download. Delete the downloaded file (its location will be pointed out in the error message) and try again.
 
-If the problem persists, the cask must be outdated. It’ll likely need a new version, but it’s possible the version has remained the same (happens occasionally when the vendor updates the app in place).
+If the problem persists, the cask must be outdated. It’ll likely need a new version, but it’s possible the version has remained the same (this happens occasionally when the vendor updates the app in-place).
 
 1. Go to the vendor’s website (`brew home <cask_name>`).
 2. Find out what the latest version is. It may be expressed in the URL used to download it.
-3. Take a look at the cask’s version (`brew info <cask_name>`) and verify it is indeed outdated. If it is:
+3. Take a look at the cask’s version (`brew info <cask_name>`) and verify it is indeed outdated. If so, it will need to be updated.
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
 ## Cask - permission denied
 
-In this case, it’s likely your user account has no admin rights so you don’t have permissions to write to `/Applications` (which is the default). You can use [`--appdir`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/USAGE.md#options) to choose where to install your applications.
+In this case, it’s likely your user account has no admin rights and therefore lacks permissions for writing to `/Applications`, which is the default install location. You can use [`--appdir`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/USAGE.md#options) to choose where to install your applications.
 
 If `--appdir` doesn’t fix the issue or you do have write permissions to `/Applications`, verify you’re the owner of the `Caskroom` directory by running `ls -dl "$(brew --prefix)/Caskroom"` and checking the third field. If you are not the owner, fix it with `sudo chown -R "$(whoami)" "$(brew --prefix)/Caskroom"`. If you are, the problem may lie in the app bundle itself.
 
-Some app bundles don’t have certain permissions that are necessary for us to move them to the appropriate location. You may check such permissions with `ls -ls <path_to_app_bundle>`. If you see something like `dr-xr-xr-x` at the start of the output, that may be the cause. To fix it, we change the app bundle’s permission to allow us to move it, and then set it back to what it was (in case the developer set those permissions deliberately). See [`litecoin`](https://github.com/Homebrew/homebrew-cask/blob/0cde71f1fea8ad62d6ec4732fcf35ac0c52d8792/Casks/litecoin.rb#L14L20) for an example of such a cask.
+Some app bundles don’t have certain permissions that are necessary for us to move them to the appropriate location. You may check such permissions with `ls -ls <path_to_app_bundle>`. If you see something like `dr-xr-xr-x` at the start of the output, that may be the cause. To fix it, we need to change the app bundle’s permission to allow us to move it, and then set it back to what it was (in case the developer set those permissions deliberately). See [`litecoin`](https://github.com/Homebrew/homebrew-cask/blob/0cde71f1fea8ad62d6ec4732fcf35ac0c52d8792/Casks/litecoin.rb#L14L20) for an example of such a cask.
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
 ## Cask - source is not there
 
-First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` the problem is [`app`](https://docs.brew.sh/Cask-Cookbook#stanza-app). The pattern is the same across [all artifacts](https://docs.brew.sh/Cask-Cookbook#at-least-one-artifact-stanza-is-also-required).
+First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` then the problem is with the [`app`](https://docs.brew.sh/Cask-Cookbook#stanza-app) stanza. This pattern is the same across [all artifacts](https://docs.brew.sh/Cask-Cookbook#at-least-one-artifact-stanza-is-also-required).
 
-Fixing this error is typically easy, and requires only a bit of time on your part. Start by downloading the package for the cask: `brew fetch <cask_name>`. The last line of output will inform you of the location of the download. Navigate there and manually unpack it. As an example, lets say the structure inside the archive is as follows:
+Fixing this error is typically easy, and requires only a bit of time on your part. Start by downloading the package for the cask: `brew fetch <cask_name>`. The last line of output will inform you of the location of the download. Navigate there and manually unpack it. As an example, let's say the structure inside the archive is as follows:
 
-```
+    .
-.
+    ├─ Files/SomeApp.app
-├─ Files/SomeApp.app
+    ├─ Files/script.sh
-├─ Files/script.sh
+    └─ README.md
-└─ README.md
-```
 
-Now, let's look at the cask (`brew cat <cask_name>`):
+Now, if we find this when looking at the cask with `brew cat <cask_name>`:
 
-```
+    (…)
-(…)
+    app "SomeApp.app"
-app "SomeApp.app"
+    (…)
-(…)
-```
 
-The cask was expecting `SomeApp.app` to be in the top directory of the archive (see how it says simply `SomeApp.app`) but the developer changed it to inside a `Files` directory. All we have to do is update that line of the cask to follow the new structure: `app 'Files/SomeApp.app'`.
+The cask expects `SomeApp.app` to be in the top directory of the archive (see how it says simply `SomeApp.app`) but the developer has since moved it to be inside a `Files` directory. All we have to do is update that line of the cask to follow the new structure: `app "Files/SomeApp.app"`.
 
 Note that occasionally the app’s name changes completely (from `SomeApp.app` to `OtherApp.app`, let's say). In these instances, the filename of the cask itself, as well as its token, must also change. Consult the [`token reference`](https://docs.brew.sh/Cask-Cookbook#token-reference) for complete instructions on the new name.
 
@@ -192,11 +205,10 @@ Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEA
 
 ## Cask - wrong number of arguments
 
-Make sure the issue really lies with your macOS version. To do so, try to install the software manually. If it is incompatible with your macOS version, it will tell you. In that case, there is nothing we can do to help you install the software, but we can add a [`depends_on macos:`](https://docs.brew.sh/Cask-Cookbook#depends_on-macos) stanza to prevent the cask from trying to install on incompatible macOS versions.
+Make sure the issue really lies with your macOS version. To do so, try to install the software manually. If it is incompatible with your macOS version, it will tell you. In that case, there is nothing we can do to help you install the software, but we can add a [`depends_on macos:`](https://docs.brew.sh/Cask-Cookbook#depends_on-macos) stanza to prevent the cask from being installed on incompatible macOS versions.
 
 Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
 
-
 ## Other local issues
 
 If your Homebrew installation gets messed up (and fixing the issues found by `brew doctor` doesn't solve the problem), reinstalling Homebrew may help to reset to a normal state. To easily reinstall Homebrew, use [Homebrew Bundle](https://github.com/Homebrew/homebrew-bundle) to automatically restore your installed formulae and casks. To do so, run `brew bundle dump`, [uninstall](https://docs.brew.sh/FAQ#how-do-i-uninstall-homebrew), [reinstall](https://docs.brew.sh/Installation) and run `brew bundle install`.

docs/FAQ.md

@@ -1,4 +1,4 @@
-# FAQ
+# FAQ (Frequently Asked Questions)
 
 ## Is there a glossary of terms around?
 

docs/Homebrew-and-Python.md

@@ -26,17 +26,17 @@ Unversioned symlinks for `python`, `python-config`, `pip` etc. are installed her
 $(brew --prefix)/opt/python/libexec/bin
 ```
 
-## Setuptools, Pip, etc.
+## Setuptools, pip, etc.
 
 The Python formulae install [pip](https://pip.pypa.io/) (as `pip3`) and [Setuptools](https://pypi.org/project/setuptools/).
 
-Setuptools can be updated via pip3, without having to re-brew Python:
+Setuptools can be updated via `pip`, without having to re-brew Python:
 
 ```sh
 python3 -m pip install --upgrade setuptools
 ```
 
-Similarly, pip3 can be used to upgrade itself via:
+Similarly, `pip` can be used to upgrade itself via:
 
 ```sh
 python3 -m pip install --upgrade pip
@@ -77,7 +77,7 @@ These should be installed via `pip install <package>`. To discover, you can use
 
 ## Brewed Python modules
 
-For brewed Python, modules installed with `pip3` or `python3 setup.py install` will be installed to the `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable Python scripts will be in `$(brew --prefix)/bin`.
+For brewed Python, modules installed with `pip` or `python3 setup.py install` will be installed to the `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable Python scripts will be in `$(brew --prefix)/bin`.
 
 Since the system Python may not know which compiler flags to set when building bindings for software installed by Homebrew, you may need to run:
 

docs/Installation.md

@@ -2,7 +2,7 @@
 
 Instructions for a supported install of Homebrew are on the [homepage](https://brew.sh).
 
-This script installs Homebrew to its default, supported, best prefix (`/usr/local` for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux) so that [you don’t need `sudo` after Homebrew's initial installation](FAQ.md#why-does-homebrew-say-sudo-is-bad) when you `brew install`. This prefix is required for most bottles (binary packages) to be used. It is a careful script; it can be run even if you have stuff installed in the preferred prefix already. It tells you exactly what it will do before it does it too. You have to confirm everything it will do before it starts.
+This script installs Homebrew to its default, supported, best prefix (`/usr/local` for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux) so that [you don’t need *sudo* after Homebrew's initial installation](FAQ.md#why-does-homebrew-say-sudo-is-bad) when you `brew install`. This prefix is required for most bottles (binary packages) to be used. It is a careful script; it can be run even if you have stuff installed in the preferred prefix already. It tells you exactly what it will do before it does it too. You have to confirm everything it will do before it starts.
 
 ## macOS Requirements
 
@@ -34,7 +34,7 @@ export HOMEBREW_INSTALL_FROM_API=1
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
 ```
 
-This will make Homebrew install formulae and casks in homebrew/core and homebrew/cask taps using Homebrew’s API instead of local checkouts of these repositories.
+This will make Homebrew install formulae and casks from the `homebrew/core` and `homebrew/cask` taps using Homebrew’s API instead of local checkouts of these repositories.
 
 ## Unattended installation
 
@@ -56,13 +56,13 @@ Technically, you can just extract (or `git clone`) Homebrew wherever you want. H
 mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew
 ```
 
-or
+or:
 
 ```sh
 git clone https://github.com/Homebrew/brew homebrew
 ```
 
-then
+then:
 
 ```sh
 eval "$(homebrew/bin/brew shellenv)"

docs/Interesting-Taps-and-Forks.md

@@ -1,4 +1,4 @@
-# Interesting Taps & Forks
+# Interesting Taps and Forks
 
 A [tap](Taps.md) is Homebrew-speak for a Git repository containing additional formulae.
 

docs/Shell-Completion.md

@@ -1,4 +1,4 @@
-# Homebrew Shell Completion
+# `brew` Shell Completion
 
 Homebrew comes with completion definitions for the `brew` command. Some packages also provide completion definitions for their own programs.
 

docs/Updating-Software-in-Homebrew.md

@@ -4,9 +4,9 @@ Did you find something in Homebrew that wasn't the latest version? You can help
 
 First, check the pull requests in the Homebrew tap repositories to make sure a PR isn't already open. If you're submitting a [formula](Formula-Cookbook.md#homebrew-terminology), check [homebrew-core](https://github.com/Homebrew/homebrew-core/pulls). If you're submitting a [cask](Formula-Cookbook.md#homebrew-terminology), check [homebrew-cask](https://github.com/Homebrew/homebrew-cask/pulls). You may also want to look through closed pull requests in the repositories, as sometimes packages run into problems preventing them from being updated and it's better to be aware of any issues before putting significant effort into an update.
 
-The [How To Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation should explain most everything you need to know about the process of creating a PR for a version update. For simple updates, this typically involves changing the URL and SHA256 values.
+The [How To Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation should explain most everything you need to know about the process of creating a PR for a version update. For simple updates, this typically involves changing the `url` and `sha256` values.
 
-However, some updates require additional changes to the package. You can look back at previous pull requests to see how others have handled things in the past but be sure to look at a variety of PRs. Sometimes packages aren't updated properly, so you may need to use your judgment to determine how to best proceed.
+However, some updates require additional changes to the package. You can look back at previous pull requests to see how others have handled things in the past, but be sure to look at a variety of PRs. Sometimes packages aren't updated properly, so you may need to use your judgment to determine how best to proceed.
 
 Once you've created the pull request in the appropriate Homebrew repository your commit(s) will be tested on our continuous integration servers, showing a green check mark if everything passed or a red X if there were failures. Maintainers will review your pull request and provide feedback about any changes that need to be made before it can be merged.