document updatePackageLastAccessTime (#3483)

Author: zivkan

docs/consume-packages/managing-the-global-packages-and-cache-folders.md

@@ -11,12 +11,12 @@ ms.topic: conceptual
 
 Whenever you install, update, or restore a package, NuGet manages packages and package information in several folders outside of your project structure:
 
-| Name | Description and Location (per user)|
+| Name | Location |
 | --- | --- |
-| global-packages | The *global-packages* folder is where NuGet installs any downloaded package. Each package is fully expanded into a subfolder that matches the package identifier and version number. Projects using the [PackageReference](package-references-in-project-files.md) format always use packages directly from this folder. When using the [packages.config](../reference/packages-config.md), packages are installed to the *global-packages* folder, then copied into the project's `packages` folder.<br/><ul><li>Windows: `%userprofile%\.nuget\packages`</li><li>Mac/Linux: `~/.nuget/packages`</li><li>Override using the NUGET_PACKAGES environment variable, the `globalPackagesFolder` or `repositoryPath` [configuration settings](../reference/nuget-config-file.md#config-section) (when using PackageReference and `packages.config`, respectively), or the `RestorePackagesPath` MSBuild property (MSBuild only). The environment variable takes precedence over the configuration setting.</li></ul> |
-| http-cache | The Visual Studio Package Manager (NuGet 3.x+) and the `dotnet` tool store copies of downloaded packages in this cache (saved as `.dat` files), organized into subfolders for each package source. Packages are not expanded, and the cache has an expiration time of 30 minutes.<br/><ul><li>Windows: `%localappdata%\NuGet\v3-cache`</li><li>Mac/Linux: `~/.local/share/NuGet/v3-cache`</li><li>Override using the NUGET_HTTP_CACHE_PATH environment variable.</li></ul> |
-| temp | A folder where NuGet stores temporary files during its various operations.<br/><li>Windows: `%temp%\NuGetScratch`</li><li>Mac: `/tmp/NuGetScratch`</li><li>Linux: `/tmp/NuGetScratch<username>`</li><li>Override using the NUGET_SCRATCH environment variable.</li></ul> |
-| plugins-cache **4.8+** | A folder where NuGet stores the results from the operation claims request.<br/><ul><li>Windows: `%localappdata%\NuGet\plugins-cache`</li><li>Mac/Linux: `~/.local/share/NuGet/plugins-cache`</li><li>Override using the NUGET_PLUGINS_CACHE_PATH environment variable.</li></ul> |
+| [global-packages](#global-packages) | <ul><li>Windows: `%userprofile%\.nuget\packages`</li><li>Mac/Linux: `~/.nuget/packages`</li><li>Override using the NUGET_PACKAGES environment variable, the `globalPackagesFolder` or `repositoryPath` [configuration settings](../reference/nuget-config-file.md#config-section) (when using PackageReference and `packages.config`, respectively), or the `RestorePackagesPath` MSBuild property (MSBuild only). The environment variable takes precedence over the configuration setting.</li></ul> |
+| [http-cache](#http-cache) | <ul><li>Windows: `%localappdata%\NuGet\v3-cache`</li><li>Mac/Linux: `~/.local/share/NuGet/v3-cache`</li><li>Override using the NUGET_HTTP_CACHE_PATH environment variable.</li></ul> |
+| [temp](#temp) | <li>Windows: `%temp%\NuGetScratch`</li><li>Mac: `/tmp/NuGetScratch`</li><li>Linux: `/tmp/NuGetScratch<username>`</li><li>Override using the NUGET_SCRATCH environment variable.</li></ul> |
+| [plugins-cache](#plugin-cache) **4.8+** | <ul><li>Windows: `%localappdata%\NuGet\plugins-cache`</li><li>Mac/Linux: `~/.local/share/NuGet/plugins-cache`</li><li>Override using the NUGET_PLUGINS_CACHE_PATH environment variable.</li></ul> |
 
 > [!Note]
 > NuGet 3.5 and earlier uses *packages-cache* instead of the *http-cache*, which is located in `%localappdata%\NuGet\Cache`.
@@ -27,6 +27,54 @@ When asked to retrieve a package, NuGet first looks in the *global-packages* fol
 
 For more information, see [What happens when a package is installed?](../concepts/package-installation-process.md).
 
+## global-packages
+
+The *global-packages* folder is where NuGet installs any downloaded package.
+Each package is fully expanded into a subfolder that matches the package identifier and version number.
+Projects using the [PackageReference](package-references-in-project-files.md) format always use packages directly from this folder.
+When using the [packages.config](../reference/packages-config.md), packages are installed to the *global-packages* folder, then copied into the project's `packages` folder.
+
+### Cleaning the global-packages directory
+
+The global-packages directory needs to be manually cleaned to remove packages that are no longer used.
+You can do this with the `dotnet nuget locals global-packages --clean` command, or the "clear NuGet local resources" button in Visual Studio's options (equivalent to `dotnet nuget locals all --clear`).
+After clearing the global-packages directory, you will need to restore your projects again to redownload all required packages.
+In Visual Studio, you may need to reload your solution to clear NuGet's "up to date restores" cache, or alternatively do a command line restore (for example, within Visual Studio's terminal window) with `msbuild -t:restore your.sln`.
+
+To clean only unused packages, it's a two step process.
+First, there is a [nuget.config setting `updatePackageLastAccessTime`](../reference/nuget-config-file.md) that should be enabled.
+This setting will cause NuGet to update each package's `.nupkg.metadata` file when it is used in a restore.
+When restore runs, but a project is considered already up to date, the package timestamps are *not* updated.
+The `.nupkg.metadata` file is the last file that NuGet will create when downloading and extracting packages during a restore or install, and is the file that restore uses to check if a package has been extracted successfully.
+
+Second, run a tool to perform the cleanup.
+After the `updatePackageLastAccessTime` setting is enabled, we recommend waiting a few days to make sure that all the packages you use regularly have had their timestamps updated.
+
+At this time, NuGet does not provide a tool or command to do this.
+You can [add a 👍 reaction to this GitHub issue](https://github.com/NuGet/Home/issues/4980) to signal your interest.
+Some community members have created their own open source NuGet cleaner tools that you can search for.
+
+If you are going to write your own cleanup tool, it is important that the `.nupkg.metadata` file is deleted if any of the other package files are deleted, so we recommend that this file is deleted first.
+Otherwise projects referencing the package may have unexpected behavior.
+If writing a cleanup tool in .NET, consider using `ConcurrencyUtilities.ExecuteWithFileLocked[Async](..)` from the [NuGet.Common package](https://www.nuget.org/packages/NuGet.Common), passing the full nupkg path of the package directory you're going to delete as the key, to avoid deleting a package that restore is trying to extract at the same time.
+The global packages directory can be programatically found with the [NuGet.Configuration package](https://www.nuget.org/packages/NuGet.Configuration).
+Use `Settings.LoadDefaultSettings(path)` to get an `ISettings` instance (you can pass `null` as the path, or pass a directory if you want to handle solutions with a nuget.config that redirects the global-packages directory), and then use `SettingsUtility.GetGlobalPackagesFolder(settings)`.
+Alternatively, you can run `dotnet nuget locals global-packages --list` as a child process and parse the output.
+
+## http-cache
+
+NuGet will cache copies of most NuGet feed communications (excluding search), organized into subfolders for each package source.
+Packages are not expanded, and files with a last modified date older than 30 minutes are typically considered expired.
+
+## temp
+
+A folder where NuGet may store temporary files during its various operations.
+
+## plugin-cache
+
+A folder where NuGet stores the results from the operation claims request.
+See the [cross platform plugins reference](../reference/extensibility/NuGet-Cross-Platform-Plugins.md) for more information.
+
 ## Viewing folder locations
 
 You can view locations using the [nuget locals command](../reference/cli-reference/cli-ref-locals.md):

docs/reference/errors-and-warnings/NU1802.md

@@ -17,6 +17,7 @@ Updating last access time on file "C:\packages\contoso.library\1.0.0\.nupkg.meta
 
 ### Solution
 
-You have enabled an experimental feature that updates the last access of the .nupkg.metadata file in the NuGet global packages folder. 
+You have enabled a feature that updates the last access of the .nupkg.metadata file in the NuGet global packages folder.
 Failures are likely to be issues with permissions.
-The details of the failure reason will be contained in the error message. Consult that information for the exact action.
+The details of the failure reason will be contained in the error message.
+Consult that information for the exact action.

docs/reference/nuget-config-file.md

@@ -30,13 +30,14 @@ Contains miscellaneous configuration settings, which can be set using the [`nuge
 
 | Key | Value |
 | --- | --- |
+| defaultPushSource | Identifies the URL or path of the package source that should be used as the default if no other package sources are found for an operation. |
 | dependencyVersion (`packages.config` only) | The default `DependencyVersion` value for package install, restore, and update, when the `-DependencyVersion` switch is not specified directly. This value is also used by the NuGet Package Manager UI. Values are `Lowest`, `HighestPatch`, `HighestMinor`, `Highest`. |
 | globalPackagesFolder | The location of the default global packages folder. The default is `%userprofile%\.nuget\packages` (Windows) or `~/.nuget/packages` (Mac/Linux). A relative path can be used in project-specific `nuget.config` files. This setting is overridden by the `NUGET_PACKAGES` environment variable, which takes precedence. |
-| repositoryPath (`packages.config` only) | The location in which to install NuGet packages instead of the default `$(Solutiondir)/packages` folder. A relative path can be used in project-specific `nuget.config` files. |
-| defaultPushSource | Identifies the URL or path of the package source that should be used as the default if no other package sources are found for an operation. |
 | http_proxy http_proxy.user http_proxy.password no_proxy | Proxy settings to use when connecting to package sources; `http_proxy` should be in the format `http://<username>:<password>@<domain>`. Passwords are encrypted and cannot be added manually. For `no_proxy`, the value is a comma-separated list of domains the bypass the proxy server. You can alternately use the http_proxy and no_proxy environment variables for those values. For additional details, see [NuGet proxy settings](http://skolima.blogspot.com/2012/07/nuget-proxy-settings.html) (skolima.blogspot.com). |
 | maxHttpRequestsPerSource | Controls the maximum number of parallel requests sent from NuGet to every package source for package dependency resolution and downloads. The default value on `dotnet.exe` is `Int32.MaxValue` which is derived from `HttpClientHandler.MaxConnectionsPerServer` property. This setting has no impact on `dotnet.exe` for `Mac OS` because the throttling limit is set to `16` to avoid too many open files error. The default value for `NuGet client tools` that runs on `.NET Framework` such as `Visual Studio` and `nuget.exe` is `64` on `Windows` and `1` on `Mono`. The default value for `Packages.config` style projects is set to `Environment.ProcessorCount`. Configuring `maxHttpRequestsPerSource` property to a value less than the default could impact NuGet performance. |
-| signatureValidationMode | Specifies the validation mode used to verify package signatures for package install, and restore. Values are `accept`, `require`. Defaults to `accept`.
+| repositoryPath (`packages.config` only) | The location in which to install NuGet packages instead of the default `$(Solutiondir)/packages` folder. A relative path can be used in project-specific `nuget.config` files. |
+| signatureValidationMode | Specifies the validation mode used to verify package signatures for package install, and restore. Values are `accept`, `require`. Defaults to `accept`. |
+| updatePackageLastAccessTime | When set to `true`, restore will update the last access time of the `.nupkg.metadata` file in the global packages folder during restore. See [the documentation on the global packages folder for more information](../consume-packages/managing-the-global-packages-and-cache-folders.md#global-packages) |
 
 **Example**:
 
@@ -48,6 +49,7 @@ Contains miscellaneous configuration settings, which can be set using the [`nuge
     <add key="http_proxy" value="http://company-squid:3128@contoso.com" />
     <add key="signatureValidationMode" value="require" />
     <add key="maxHttpRequestsPerSource" value="16" />
+    <add key="updatePackageLastAccessTime" value="false" />
 </config>
 ```