Skip to content

Commit

Permalink
WIP systematize builtins.fetchTree docs
Browse files Browse the repository at this point in the history 
The renaming task is splatting everything together into markdown lists.
I think I want to do that with the lowdown AST; I opened
kristapsdz/lowdown#131 for this purpose

PR #9273 should be able to improve upon this a good bit, but I think it
is still a useful stepping stone.
  • Loading branch information
@Ericson2314
Ericson2314 committed Jan 9, 2024
1 parent 84aa8e9 commit 7c5e178
Show file tree
Hide file tree
Showing 8 changed files with 400 additions and 180 deletions.
125 changes: 0 additions & 125 deletions src/libexpr/primops/fetchTree.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,131 +227,6 @@ static RegisterPrimOp primop_fetchTree({
document) if `fetchTree` was a curried call with the first paramter for
`type` or an attribute like `builtins.fetchTree.git`! -->
- `"file"`
Place a plain file into the Nix store.
This is similar to [`builtins.fetchurl`](@docroot@/language/builtins.md#builtins-fetchurl)
- `url` (String, required)
Supported protocols:
- `https`
> **Example**
>
> ```nix
> fetchTree {
> type = "file";
> url = "https://example.com/index.html";
> }
> ```
- `http`
Insecure HTTP transfer for legacy sources.
> **Warning**
>
> HTTP performs no encryption or authentication.
> Use a `narHash` known in advance to ensure the output has expected contents.
- `file`
A file on the local file system.
> **Example**
>
> ```nix
> fetchTree {
> type = "file";
> url = "file:///home/eelco/nix/README.md";
> }
> ```
- `"tarball"`
Download a tar archive and extract it into the Nix store.
This has the same underyling implementation as [`builtins.fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball)
- `url` (String, required)
> **Example**
>
> ```nix
> fetchTree {
> type = "tarball";
> url = "https://github.com/NixOS/nixpkgs/tarball/nixpkgs-23.11";
> }
> ```
- `"git"`
Fetch a Git tree and copy it to the Nix store.
This is similar to [`builtins.fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit).
- `url` (String, required)
The URL formats supported are the same as for Git itself.
> **Example**
>
> ```nix
> fetchTree {
> type = "git";
> url = "[email protected]:NixOS/nixpkgs.git";
> }
> ```
> **Note**
>
> If the URL points to a local directory, and no `ref` or `rev` is given, Nix will only consider files added to the Git index, as listed by `git ls-files` but use the *current file contents* of the Git working directory.
- `ref` (String, optional)
A [Git reference](https://git-scm.com/book/en/v2/Git-Internals-Git-References), such as a branch or tag name.
Default: `"HEAD"`
- `rev` (String, optional)
A Git revision; a commit hash.
Default: the tip of `ref`
- `shallow` (Bool, optional)
Make a shallow clone when fetching the Git tree.
Default: `false`
- `submodules` (Bool, optional)
Also fetch submodules if available.
Default: `false`
- `allRefs` (Bool, optional)
If set to `true`, always fetch the entire repository, even if the latest commit is still in the cache.
Otherwise, only the latest commit is fetched if it is not already cached.
Default: `false`
- `lastModified` (Integer, optional)
Unix timestamp of the fetched commit.
If set, pass through the value to the output attribute set.
Otherwise, generated from the fetched Git tree.
- `revCount` (Integer, optional)
Number of revisions in the history of the Git repository before the fetched commit.
If set, pass through the value to the output attribute set.
Otherwise, generated from the fetched Git tree.
The following input types are still subject to change:
- `"path"`
Expand Down
11 changes: 8 additions & 3 deletions src/libfetchers/fetchers.hh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,14 +149,19 @@ struct InputScheme
*/
virtual std::string_view schemeName() const = 0;

/**
* Longform description of this scheme, for documentation purposes.
*/
virtual std::string schemeDescription() const = 0;

/**
* Allowed attributes in an attribute set that is converted to an
* input.
* input, and documentation for each attribute.
*
* `type` is not included from this set, because the `type` field is
* `type` is not included from this map, because the `type` field is
parsed first to choose which scheme; `type` is always required.
*/
virtual StringSet allowedAttrs() const = 0;
virtual StringMap allowedAttrs() const = 0;

virtual ParsedURL toURL(const Input & input) const;

Expand Down
160 changes: 143 additions & 17 deletions src/libfetchers/git.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -191,25 +191,151 @@ struct GitInputScheme : InputScheme
return "git";
}

StringSet allowedAttrs() const override
std::string schemeDescription() const override
{
return stripIndentation(R"(
Fetch a Git tree and copy it to the Nix store.
This is similar to [`builtins.fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit).
)");
}

StringMap allowedAttrs() const override
{
return {
"url",
"ref",
"rev",
"shallow",
"submodules",
"lastModified",
"revCount",
"narHash",
"allRefs",
"name",
"dirtyRev",
"dirtyShortRev",
"verifyCommit",
"keytype",
"publicKey",
"publicKeys",
{
"url",
R"(
(String, required)
The URL formats supported are the same as for Git itself.
> **Example**
>
> ```nix
> fetchTree {
> type = "git";
> url = "[email protected]:NixOS/nixpkgs.git";
> }
> ```
> **Note**
>
> If the URL points to a local directory, and no `ref` or `rev` is given, Nix will only consider files added to the Git index, as listed by `git ls-files` but use the *current file contents* of the Git working directory.
)",
},
{
"ref",
R"(
(String, optional)
A [Git reference](https://git-scm.com/book/en/v2/Git-Internals-Git-References), such as a branch or tag name.
Default: `"HEAD"`
)",
},
{
"rev",
R"(
(String, optional)
A Git revision; a commit hash.
Default: the tip of `ref`
)",
},
{
"shallow",
R"(
(Bool, optional)
Make a shallow clone when fetching the Git tree.
Default: `false`
)",
},
{
"submodules",
R"(
(Bool, optional)
Also fetch submodules if available.
Default: `false`
)",
},
{
"lastModified",
R"(
(Integer, optional)
Unix timestamp of the fetched commit.
If set, pass through the value to the output attribute set.
Otherwise, generated from the fetched Git tree.
)",
},
{
"revCount",
R"(
(Integer, optional)
Number of revisions in the history of the Git repository before the fetched commit.
If set, pass through the value to the output attribute set.
Otherwise, generated from the fetched Git tree.
)",
},
{
"narHash",
R"(
)",
},
{
"allRefs",
R"(
(Bool, optional)
If set to `true`, always fetch the entire repository, even if the latest commit is still in the cache.
Otherwise, only the latest commit is fetched if it is not already cached.
Default: `false`
)",
},
{
"name",
R"(
)",
},
{
"dirtyRev",
R"(
)",
},
{
"dirtyShortRev",
R"(
)",
},
{
"verifyCommit",
R"(
)",
},
{
"keytype",
R"(
)",
},
{
"publicKey",
R"(
)",
},
{
"publicKeys",
R"(
)",
},
};
}

Expand Down
Loading

0 comments on commit 7c5e178

Please sign in to comment.