Skip to content

Commit cc2f99a

Browse files
kzukzu
committed
Cleanup including markdown from package
1 parent 8f2c5f8 commit cc2f99a

File tree

1 file changed

+2
-219
lines changed

1 file changed

+2
-219
lines changed

‎src/File/readme.md

Lines changed: 2 additions & 219 deletions
Original file line numberDiff line numberDiff line change
@@ -1,221 +1,4 @@
11
<!-- include ../../readme.md#content -->
2-
<!-- #content -->
3-
A dotnet global tool for downloading and updating loose files from arbitrary URLs.
4-
5-
Installing or updating (same command can be used for both):
6-
7-
```
8-
dotnet tool update -g dotnet-file
9-
```
10-
11-
To get the CI version:
12-
13-
```
14-
dotnet tool update -g dotnet-file --no-cache --add-source https://pkg.kzu.io/index.json
15-
```
16-
17-
Usage:
18-
19-
dotnet file [add|changes|delete|list|sync|update] [file or url]*
20-
21-
Actions
22-
add downloads a file or GitHub repository or directory from a URL
23-
changes checks remote URLs for changes and lists the status of local files
24-
delete deletes a file and its corresponding config entry from the local directory
25-
init initializes the local directory from one or more remote .netconfig files
26-
list lists the config entries and the status of their corresponding files
27-
sync synchronizes with remote URLs, deleting local files and directories as needed
28-
update updates local files from remote URLs, does not prune deleted remote files
29-
30-
Status
31-
= <- [url] remote file equals local file
32-
✓ <- [url] local file updated with remote file
33-
^ <- [url] remote file is newer (ETags mismatch)
34-
? <- [url] local file not found for remote file
35-
x <- [url] error processing the entry
36-
37-
38-
All arguments after the action are tried for URL parsing automatically to
39-
disambiguate file (local path) from url (remote file location).
40-
41-
Examples:
42-
43-
dotnet file init [url] // seeds the current directory with all files/URLs listed in a remote URL
44-
dotnet file add [url] // downloads a file to the current directory and adds its URL+ETag in dotnet-config
45-
dotnet file add [url] [file] // downloads the url to the (relative) file local path specifed and adds
46-
// its URL+ETag in dotnet-config
47-
dotnet file add [url] . // downloads the url to the current directory and stores URL+ETag in dotnet-config,
48-
// ignoring the source directory structure
49-
dotnet file add [url] docs/ // downloads the url to the specified directory, preserving the source directory structure
50-
dotnet file add [url] docs/. // downloads the url to the specified directory, flattening the source directory structure
51-
dotnet file update [file] // updates a specific file, based on its dotnet-config configuration
52-
dotnet file update [url] // updates a specific file by its url, based on its dotnet-config configuration
53-
dotnet file update // updates all recorded files, according to the dotnet-config configuration
54-
dotnet file sync // just like update, but also prunes files/folders removed from their remote urls
55-
dotnet file delete [file] // deletes a local file and its entry in .netconfig
56-
dotnet file list // lists all configured files
57-
dotnet file changes // lists all configured files and their status with regards to the configured
58-
// remote URL and ETag matching
59-
60-
> NOTE: to download a file from GitHub to the current directory, ignoring the remote folder structure,
61-
> specify `.` as the `[file]` argument after the `[url]`. Otherwise, the default will be to match the
62-
> directory structure of the source file.
63-
64-
65-
After downloading a file, a new entry is created in a local `.netconfig` file, which
66-
leverages [dotnet config](https://github.com/kzu/dotnet-config):
67-
68-
[file "relative file path"]
69-
url = [url]
70-
etag = [etag]
71-
72-
This information is used to later update the file contents if necessary, by issuing a
73-
conditional http get to retrieve updates. It’s generally advisable to commit the .netconfig file
74-
to source control, so that updating is simply a matter of running `dotnet file update`.
75-
76-
> Note: `dotnet file update [url]` behaves just like `dotnet file add [url]` when a matching
77-
> entry for the file isn't found in the `.netconfig` file.
78-
79-
If you want to skip further synchronization of a file, you can add `skip` to the entire:
80-
81-
[file "readme.md"]
82-
url = [url]
83-
skip
84-
85-
Symbols are used to denote actions (pending or performed) on files:
86-
87-
* `√`: file has no pending updated (ETag matches) or it was just downloaded successfully.
88-
* `^`: file has pending updates (ETag doesn't match the remote).
89-
* `=`: no changes to file were necessary in an update
90-
* `?`: file not found locally. A new version can be downloaded from the remote.
91-
* `x`: could not update file or refresh ETag status, with reason noted in subsequent line.
92-
93-
Downloading entire repositories or specific directories within them is supported through the
94-
[GitHub CLI](https://cli.github.com/manual/installation), which must be installed previously.
95-
You can verify you have the property authentication and access in place by running the following
96-
GH CLI command:
97-
98-
gh repo view org/repo
99-
100-
If you can view the output (would be the README from the repo), you can download files from it
101-
with `dotnet-file`.
102-
103-
104-
Private repositories are supported from GitHub and BitBucket through the
105-
[Git Credentials Manager Core](https://github.blog/2020-07-02-git-credential-manager-core-building-a-universal-authentication-experience/)
106-
project.
107-
108-
When adding a file, it's possible to customize the local file location by specifying an absolute
109-
or relative file path, as follows:
110-
111-
* `src/External/File.cs`: fully custom target file path, doesn't need to match source URI file name
112-
or directory structure.
113-
* `src/External/`: use the given directory as the base directory, but otherwise preserve the source
114-
URI directory structure and file name.
115-
* `src/External/.`: download to the given directory, without recreating source URI directory structure,
116-
using the source file name only.
117-
* `.` (a single dot character as the target path): download to the current directory, don't preserve
118-
source URI directory structure, use source file name only.
119-
120-
121-
Concrete examples:
122-
123-
> dotnet file add https://github.com/devlooped/dotnet-file/blob/main/azure-pipelines.yml
124-
azure-pipelines.yml √ <- https://github.com/devlooped/dotnet-file/blob/main/azure-pipelines.yml
125-
126-
> dotnet file add https://github.com/devlooped/dotnet-file/blob/main/docs/img/icon.png img/icon.png
127-
img/icon.png √ <- https://github.com/devlooped/dotnet-file/blob/main/docs/img/icon.png
128-
129-
> dotnet file list
130-
azure-pipelines.yml = <- https://github.com/devlooped/dotnet-file/blob/main/azure-pipelines.yml
131-
img/icon.png = <- https://github.com/devlooped/dotnet-file/blob/main/docs/img/icon.png
132-
133-
> del img\icon.png
134-
> dotnet file list
135-
azure-pipelines.yml = <- https://github.com/devlooped/dotnet-file/blob/main/azure-pipelines.yml
136-
img/icon.png ? <- https://github.com/devlooped/dotnet-file/blob/main/docs/img/icon.png
137-
138-
# missing file downloaded successfully
139-
> dotnet file update
140-
azure-pipelines.yml = <- https://github.com/devlooped/dotnet-file/blob/main/azure-pipelines.yml
141-
img/icon.png √ <- https://github.com/devlooped/dotnet-file/blob/main/docs/img/icon.png
142-
143-
# file updated on remote, changes detected
144-
> dotnet file changes
145-
azure-pipelines.yml ^ <- https://github.com/devlooped/dotnet-file/blob/main/azure-pipelines.yml
146-
img/icon.png = <- https://github.com/devlooped/dotnet-file/blob/main/docs/img/icon.png
147-
148-
# file renamed or deleted from remote
149-
> dotnet file changes
150-
azure-pipelines.yml = <- https://github.com/devlooped/dotnet-file/raw/main/azure-pipelines.yml
151-
img/icon.png x <- https://github.com/devlooped/dotnet-file/blob/main/docs/img/icon.png
152-
404: Not Found
153-
154-
# download entire directory to local dir matching remote folder structure
155-
> dotnet file add https://github.com/dotnet/runtime/tree/main/docs/coding-guidelines/api-guidelines
156-
api-guidelines => fetching via gh cli...
157-
docs/coding-guidelines/api-guidelines/README.md √ <- https://github.com/dotnet/runtime/main/docs/coding-guidelines/api-guidelines/README.md
158-
docs/coding-guidelines/api-guidelines/System.Memory.md √ <- https://github.com/dotnet/runtime/main/docs/coding-guidelines/api-guidelines/System.Memory.md
159-
docs/coding-guidelines/api-guidelines/nullability.md √ <- https://github.com/dotnet/runtime/main/docs/coding-guidelines/api-guidelines/nullability.md
160-
...
161-
162-
# download entire directory to a local subdirectory, from where dir structure will match remote structure
163-
> dotnet file add https://github.com/dotnet/runtime/tree/main/docs/coding-guidelines/api-guidelines external/dotnet/
164-
external/dotnet/ => fetching via gh cli...
165-
external/dotnet/docs/coding-guidelines/api-guidelines/README.md √ <- https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/api-guidelines/README.md
166-
external/dotnet/docs/coding-guidelines/api-guidelines/System.Memory.md √ <- https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/api-guidelines/System.Memory.md
167-
external/dotnet/docs/coding-guidelines/api-guidelines/nullability.md √ <- https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/api-guidelines/nullability.md
168-
...
169-
170-
<!-- #content -->
171-
<!-- ../../readme.md#content -->
172-
1732
<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
174-
# Sponsors
175-
176-
<!-- sponsors.md -->
177-
[![Clarius Org](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/clarius.png "Clarius Org")](https://github.com/clarius)
178-
[![Kirill Osenkov](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/KirillOsenkov.png "Kirill Osenkov")](https://github.com/KirillOsenkov)
179-
[![MFB Technologies, Inc.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/MFB-Technologies-Inc.png "MFB Technologies, Inc.")](https://github.com/MFB-Technologies-Inc)
180-
[![Stephen Shaw](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/decriptor.png "Stephen Shaw")](https://github.com/decriptor)
181-
[![Torutek](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/torutek-gh.png "Torutek")](https://github.com/torutek-gh)
182-
[![DRIVE.NET, Inc.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/drivenet.png "DRIVE.NET, Inc.")](https://github.com/drivenet)
183-
[![Ashley Medway](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/AshleyMedway.png "Ashley Medway")](https://github.com/AshleyMedway)
184-
[![Keith Pickford](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/Keflon.png "Keith Pickford")](https://github.com/Keflon)
185-
[![Thomas Bolon](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/tbolon.png "Thomas Bolon")](https://github.com/tbolon)
186-
[![Kori Francis](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/kfrancis.png "Kori Francis")](https://github.com/kfrancis)
187-
[![Toni Wenzel](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/twenzel.png "Toni Wenzel")](https://github.com/twenzel)
188-
[![Giorgi Dalakishvili](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/Giorgi.png "Giorgi Dalakishvili")](https://github.com/Giorgi)
189-
[![Uno Platform](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/unoplatform.png "Uno Platform")](https://github.com/unoplatform)
190-
[![Dan Siegel](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/dansiegel.png "Dan Siegel")](https://github.com/dansiegel)
191-
[![Reuben Swartz](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/rbnswartz.png "Reuben Swartz")](https://github.com/rbnswartz)
192-
[![Jacob Foshee](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/jfoshee.png "Jacob Foshee")](https://github.com/jfoshee)
193-
[![](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/Mrxx99.png "")](https://github.com/Mrxx99)
194-
[![Eric Johnson](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/eajhnsn1.png "Eric Johnson")](https://github.com/eajhnsn1)
195-
[![Ix Technologies B.V.](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/IxTechnologies.png "Ix Technologies B.V.")](https://github.com/IxTechnologies)
196-
[![David JENNI](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/davidjenni.png "David JENNI")](https://github.com/davidjenni)
197-
[![Jonathan ](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/Jonathan-Hickey.png "Jonathan ")](https://github.com/Jonathan-Hickey)
198-
[![Oleg Kyrylchuk](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/okyrylchuk.png "Oleg Kyrylchuk")](https://github.com/okyrylchuk)
199-
[![Charley Wu](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/akunzai.png "Charley Wu")](https://github.com/akunzai)
200-
[![Jakob Tikjøb Andersen](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/jakobt.png "Jakob Tikjøb Andersen")](https://github.com/jakobt)
201-
[![Seann Alexander](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/seanalexander.png "Seann Alexander")](https://github.com/seanalexander)
202-
[![Tino Hager](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/tinohager.png "Tino Hager")](https://github.com/tinohager)
203-
[![Mark Seemann](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/ploeh.png "Mark Seemann")](https://github.com/ploeh)
204-
[![Ken Bonny](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/KenBonny.png "Ken Bonny")](https://github.com/KenBonny)
205-
[![Simon Cropp](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/SimonCropp.png "Simon Cropp")](https://github.com/SimonCropp)
206-
[![agileworks-eu](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/agileworks-eu.png "agileworks-eu")](https://github.com/agileworks-eu)
207-
[![sorahex](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/sorahex.png "sorahex")](https://github.com/sorahex)
208-
[![Zheyu Shen](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/arsdragonfly.png "Zheyu Shen")](https://github.com/arsdragonfly)
209-
[![Vezel](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/vezel-dev.png "Vezel")](https://github.com/vezel-dev)
210-
[![ChilliCream](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/ChilliCream.png "ChilliCream")](https://github.com/ChilliCream)
211-
[![4OTC](https://raw.githubusercontent.com/devlooped/sponsors/main/.github/avatars/4OTC.png "4OTC")](https://github.com/4OTC)
212-
213-
214-
<!-- sponsors.md -->
215-
216-
[![Sponsor this project](https://raw.githubusercontent.com/devlooped/sponsors/main/sponsor.png "Sponsor this project")](https://github.com/sponsors/devlooped)
217-
&nbsp;
218-
219-
[Learn more about GitHub Sponsors](https://github.com/sponsors)
220-
221-
<!-- https://github.com/devlooped/sponsors/raw/main/footer.md -->
3+
<!-- prevent expansion via CI markdown includes -->
4+
<!-- exclude -->

0 commit comments

Comments
 (0)