dotnet-file 1.6.2

dotnet tool install --global dotnet-file --version 1.6.2                
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local dotnet-file --version 1.6.2                
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=dotnet-file&version=1.6.2                
nuke :add-package dotnet-file --version 1.6.2                

A dotnet global tool for downloading and updating loose files from arbitrary URLs.

Installing or updating (same command can be used for both):

dotnet tool update -g dotnet-file

To get the CI version:

dotnet tool update -g dotnet-file --no-cache --add-source


dotnet file [add|changes|delete|list|sync|update] [file or url]*

    add        downloads a file or GitHub repository or directory from a URL
    changes    checks remote URLs for changes and lists the status of local files
    delete     deletes a file and its corresponding config entry from the local directory
    init       initializes the local directory from one or more remote .netconfig files
    list       lists the config entries and the status of their corresponding files
    sync       synchronizes with remote URLs, deleting local files and directories as needed
    update     updates local files from remote URLs, does not prune deleted remote files

  = <- [url]   remote file equals local file
  ✓ <- [url]   local file updated with remote file
  ^ <- [url]   remote file is newer (ETags mismatch)
  ? <- [url]   local file not found for remote file
  x <- [url]   error processing the entry

All arguments after the action are tried for URL parsing automatically to disambiguate file (local path) from url (remote file location).


dotnet file init [url]          // seeds the current directory with all files/URLs listed in a remote URL
dotnet file add [url]           // downloads a file to the current directory and adds its URL+ETag in dotnet-config
dotnet file add [url] [file]    // downloads the url to the (relative) file local path specifed and adds
                                // its URL+ETag in dotnet-config
dotnet file add [url] .         // downloads the url to the current directory and stores URL+ETag in dotnet-config, 
                                // ignoring the source directory structure
dotnet file add [url] docs/     // downloads the url to the specified directory, preserving the source directory structure
dotnet file add [url] docs/.    // downloads the url to the specified directory, flattening the source directory structure
dotnet file update [file]       // updates a specific file, based on its dotnet-config configuration
dotnet file update [url]        // updates a specific file by its url, based on its dotnet-config configuration
dotnet file update              // updates all recorded files, according to the dotnet-config configuration
dotnet file sync                // just like update, but also prunes files/folders removed from their remote urls
dotnet file delete [file]       // deletes a local file and its entry in .netconfig
dotnet file list                // lists all configured files
dotnet file changes             // lists all configured files and their status with regards to the configured 
                                // remote URL and ETag matching

The target path is determined by the following rules:

  • If [file] = .: download to the current directory, ignoring the source directory structure.
  • If [url] ends with /: download to the current directory, preserving the source directory structure from that point onwards (i.e. for GitHub tree/dir URLs)
  • Otherwise, match the directory structure of the source file.

After downloading a file, a new entry is created in a local .netconfig file, which leverages dotnet config:

[file "relative file path"]
  url = [url]
  etag = [etag]

This information is used to later update the file contents if necessary, by issuing a conditional http get to retrieve updates. It’s generally advisable to commit the .netconfig file to source control, so that updating is simply a matter of running dotnet file update.

Note: dotnet file update [url] behaves just like dotnet file add [url] when a matching entry for the file isn't found in the .netconfig file.

If you want to skip further synchronization of a file, you can add skip to the entire:

[file ""]
  url = [url]

Symbols are used to denote actions (pending or performed) on files:

  • : file has no pending updated (ETag matches) or it was just downloaded successfully.
  • ^: file has pending updates (ETag doesn't match the remote).
  • =: no changes to file were necessary in an update
  • ?: file not found locally. A new version can be downloaded from the remote.
  • x: could not update file or refresh ETag status, with reason noted in subsequent line.

Downloading entire repositories or specific directories within them is supported through the GitHub CLI, which must be installed previously. You can verify you have the property authentication and access in place by running the following GH CLI command:

gh repo view org/repo

If you can view the output (would be the README from the repo), you can download files from it with dotnet-file.

Private repositories are supported from GitHub and BitBucket through the Git Credentials Manager Core project.

When adding a file, it's possible to customize the local file location by specifying an absolute or relative file path, as follows:

  • src/External/File.cs: fully custom target file path, doesn't need to match source URI file name or directory structure.
  • src/External/: use the given directory as the base directory, but otherwise preserve the source URI directory structure and file name.
  • src/External/.: download to the given directory, without recreating source URI directory structure, using the source file name only.
  • . (a single dot character as the target path): download to the current directory, don't preserve source URI directory structure, use source file name only.

Concrete examples:

> dotnet file add
azure-pipelines.yml √ <-

> dotnet file add img/icon.png
img/icon.png √ <-

> dotnet file list
azure-pipelines.yml = <-
img/icon.png        = <-

> del img\icon.png
> dotnet file list
azure-pipelines.yml = <-
img/icon.png        ? <-

# missing file downloaded successfully
> dotnet file update
azure-pipelines.yml = <-
img/icon.png        √ <-

# file updated on remote, changes detected
> dotnet file changes
azure-pipelines.yml ^ <-
img/icon.png        = <-

# file renamed or deleted from remote
> dotnet file changes
azure-pipelines.yml = <-
img/icon.png        x <-
                         404: Not Found

# download entire directory to local dir matching remote folder structure
> dotnet file add
api-guidelines  => fetching via gh cli...
docs/coding-guidelines/api-guidelines/        √ <-
docs/coding-guidelines/api-guidelines/ √ <-
docs/coding-guidelines/api-guidelines/   √ <-

# download entire directory to a local subdirectory, from where dir structure will match remote structure
> dotnet file add external/dotnet/
external/dotnet/ => fetching via gh cli...
external/dotnet/docs/coding-guidelines/api-guidelines/        √ <-
external/dotnet/docs/coding-guidelines/api-guidelines/ √ <-
external/dotnet/docs/coding-guidelines/api-guidelines/   √ <-


Clarius Org Kirill Osenkov MFB Technologies, Inc. Stephen Shaw Torutek DRIVE.NET, Inc. Ashley Medway Keith Pickford Thomas Bolon Kori Francis Toni Wenzel Giorgi Dalakishvili Uno Platform Dan Siegel Reuben Swartz Jacob Foshee alternate text is missing from this package README image Eric Johnson Ix Technologies B.V. David JENNI Jonathan Oleg Kyrylchuk Charley Wu Jakob Tikjøb Andersen Seann Alexander Tino Hager Mark Seemann Ken Bonny Simon Cropp agileworks-eu sorahex Zheyu Shen Vezel ChilliCream 4OTC

Sponsor this project  

Learn more about GitHub Sponsors

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last updated
1.6.2 2,071 7/8/2024
1.5.1-beta 131 4/9/2024
1.5.0 756 6/25/2024
1.4.1 53,676 11/17/2022
1.4.0 7,225 6/29/2022
1.3.1 8,641 10/27/2021
1.3.0 1,011 10/4/2021
1.2.1 1,895 7/16/2021
1.2.0 1,482 5/7/2021
1.0.1 1,923 3/1/2021
1.0.0 330 2/26/2021
0.9.4 428 1/25/2021
0.9.3 720 12/15/2020
0.9.2 419 12/10/2020
0.9.1 418 12/9/2020
0.9.0 395 12/8/2020
0.2.46 380 12/8/2020
0.2.41 394 12/5/2020
0.2.40 430 10/24/2020
0.2.39 564 9/26/2020
0.2.38 563 9/26/2020
0.2.37 546 9/26/2020
0.2.36 552 9/26/2020
0.2.34 567 9/26/2020
0.2.33 418 8/26/2020
0.2.32 423 8/26/2020
0.2.31 420 8/26/2020
0.2.28 436 8/25/2020
0.2.27 465 8/25/2020
0.2.26 458 8/25/2020
0.2.25 479 8/25/2020
0.2.24 577 8/21/2020
0.2.23 430 8/20/2020
0.2.22 463 8/20/2020
0.2.21 472 8/16/2020
0.2.20 442 8/16/2020
0.2.19 451 8/16/2020
0.2.18 514 8/16/2020
0.2.17 517 8/16/2020
0.2.16 610 5/22/2020
0.2.13 479 5/21/2020
0.2.12 503 5/21/2020
0.2.11 466 5/21/2020
0.2.10 465 5/21/2020
0.2.9 472 4/30/2020
0.2.8 463 4/30/2020
0.2.7 500 4/30/2020
0.2.6 499 3/6/2020