From 9e1635c9d7b41aeadb2c133608ce3a52f34ee7bc Mon Sep 17 00:00:00 2001
From: Pradyun Gedam <pradyunsg@users.noreply.github.com>
Date: Fri, 11 Mar 2022 07:52:36 +0000
Subject: [PATCH 1/2] Document the location of pip's cache

This makes it easier for users to discover this information.
---
 docs/html/topics/caching.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/html/topics/caching.md b/docs/html/topics/caching.md
index d584859c334..1e43a364494 100644
--- a/docs/html/topics/caching.md
+++ b/docs/html/topics/caching.md
@@ -50,6 +50,43 @@ pip now caches wheels when building from an immutable Git reference
 (i.e. a commit hash).
 ```
 
+## Where is the cache stored
+
+```{caution}
+The exact filesystem structure of pip's cache's contents is considered to be
+an implementation detail and may change between any two versions of pip.
+```
+
+### `pip cache dir`
+
+```{versionadded} 20.1
+
+```
+
+You can use `pip cache dir` to get the cache directory that pip is currently configured to use.
+
+### Default paths
+
+````{tab} Unix
+```
+~/.cache/pip
+```
+
+pip will also respect `XDG_CACHE_HOME`.
+````
+
+````{tab} MacOS
+```
+~/Library/Caches/pip
+```
+````
+
+````{tab} Windows
+```
+%LocalAppData%\pip\Cache
+```
+````
+
 ## Avoiding caching
 
 pip tries to use its cache whenever possible, and it is designed do the right

From 8774f06e8c829fb988db28e6ef29b3aac9a17b06 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam <pradyunsg@users.noreply.github.com>
Date: Fri, 11 Mar 2022 07:54:10 +0000
Subject: [PATCH 2/2] Flesh out the cache management section

This provides information on using the `pip cache` command to do things.
---
 docs/html/topics/caching.md | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/docs/html/topics/caching.md b/docs/html/topics/caching.md
index 1e43a364494..929ac3541df 100644
--- a/docs/html/topics/caching.md
+++ b/docs/html/topics/caching.md
@@ -118,8 +118,23 @@ It is also a good idea to remove the offending cached wheel using the
 
 The {ref}`pip cache` command can be used to manage pip's cache.
 
-The exact filesystem structure of pip's cache is considered to be an
-implementation detail and may change between any two versions of pip.
+### General overview
+
+`pip cache info` provides an overview of the contents of pip's cache, such as the total size and location of various parts of it.
+
+### Removing a single package
+
+`pip cache remove setuptools` removes all wheel files related to setuptools from pip's cache.
+
+### Removing the cache
+
+`pip cache purge` will clear all wheel files from pip's cache.
+
+### Listing cached files
+
+`pip cache list` will list all wheel files from pip's cache.
+
+`pip cache list setuptools` will list all setuptools-related wheel files from pip's cache.
 
 ## Disabling caching