diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index 478b67ce8..877fd3a1b 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -434,88 +434,93 @@ stdenv.mkDerivation { … } - - Fetching a private repository over SSH - builtins.fetchGit { + Here are some examples of how to use + fetchGit. + + + + + To fetch a private repository over SSH: + + builtins.fetchGit { url = "git@github.com:my-secret/repository.git"; ref = "master"; rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; } - - - Fetching an arbitrary ref - builtins.fetchGit { + + + + To fetch an arbitrary reference: + + builtins.fetchGit { url = "https://github.com/NixOS/nix.git"; ref = "refs/heads/0.5-release"; } - + - - Fetching a repository's specific commit on an arbitrary branch - - If the revision you're looking for is in the default branch - of the git repository you don't strictly need to specify - the branch name in the ref attribute. - - - However, if the revision you're looking for is in a future - branch for the non-default branch you will need to specify - the the ref attribute as well. - - builtins.fetchGit { + + + If the revision you're looking for is in the default branch + of the git repository you don't strictly need to specify + the branch name in the ref attribute. + + + However, if the revision you're looking for is in a future + branch for the non-default branch you will need to specify + the the ref attribute as well. + + + builtins.fetchGit { url = "https://github.com/nixos/nix.git"; rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; ref = "1.11-maintenance"; } - - - It is nice to always specify the branch which a revision - belongs to. Without the branch being specified, the - fetcher might fail if the default branch changes. - Additionally, it can be confusing to try a commit from a - non-default branch and see the fetch fail. If the branch - is specified the fault is much more obvious. - - - - - Fetching a repository's specific commit on the default branch - - If the revision you're looking for is in the default branch - of the git repository you may omit the - ref attribute. - - builtins.fetchGit { + + + It is nice to always specify the branch which a revision + belongs to. Without the branch being specified, the + fetcher might fail if the default branch changes. + Additionally, it can be confusing to try a commit from a + non-default branch and see the fetch fail. If the branch + is specified the fault is much more obvious. + + + + + + + If the revision you're looking for is in the default branch + of the git repository you may omit the + ref attribute. + + builtins.fetchGit { url = "https://github.com/nixos/nix.git"; rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; } - + - - Fetching a tag - builtins.fetchGit { + + To fetch a specific tag: + builtins.fetchGit { url = "https://github.com/nixos/nix.git"; ref = "refs/tags/1.9"; } - + - - Fetching the latest version of a remote branch - - builtins.fetchGit can behave impurely - fetch the latest version of a remote branch. - - Nix will refetch the branch in accordance to - . - This behavior is disabled in - Pure evaluation mode. + + To fetch the latest version of a remote branch: builtins.fetchGit { url = "ssh://git@github.com/nixos/nix.git"; ref = "master"; } - + Nix will refetch the branch in accordance to + . + This behavior is disabled in Pure + evaluation mode. + + diff --git a/doc/manual/packages/copy-closure.xml b/doc/manual/packages/copy-closure.xml index 012030e3e..a336fb293 100644 --- a/doc/manual/packages/copy-closure.xml +++ b/doc/manual/packages/copy-closure.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ssec-copy-closure"> -Copying Closures Via SSH +Copying Closures via SSH The command nix-copy-closure copies a Nix diff --git a/doc/manual/packages/s3-substituter.xml b/doc/manual/packages/s3-substituter.xml index 868b5a66d..aa5df2026 100644 --- a/doc/manual/packages/s3-substituter.xml +++ b/doc/manual/packages/s3-substituter.xml @@ -5,10 +5,10 @@ version="5.0" xml:id="ssec-s3-substituter"> -Serving a Nix store via AWS S3 or S3-compatible Service +Serving a Nix store via S3 Nix has built-in support for storing and fetching store paths -from Amazon S3 and S3 compatible services. This uses the same +from Amazon S3 and S3-compatible services. This uses the same binary cache mechanism that Nix usually uses to fetch prebuilt binaries from cache.nixos.org. @@ -170,13 +170,22 @@ the S3 URL: } ]]> - - Uploading with a specific credential profile for Amazon S3 - nix copy --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2' nixpkgs.hello - - - Uploading to an S3-Compatible Binary Cache - nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello - + +
Examples + +To upload with a specific credential profile for Amazon S3: + + +nix copy --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2' nixpkgs.hello + + +To upload to an S3-compatible binary cache: + + +nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello + + +
+ diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md index f60af9d24..8faf4b939 100644 --- a/doc/manual/src/expressions/builtins.md +++ b/doc/manual/src/expressions/builtins.md @@ -169,70 +169,76 @@ For instance, `derivation` is also available as `builtins.derivation`. A Boolean parameter that specifies whether submodules should be checked out. Defaults to `false`. - + Here are some examples of how to use `fetchGit`. - builtins.fetchGit { - url = "git@github.com:my-secret/repository.git"; - ref = "master"; - rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; - } + - To fetch a private repository over SSH: + + builtins.fetchGit { + url = "git@github.com:my-secret/repository.git"; + ref = "master"; + rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; + } - builtins.fetchGit { - url = "https://github.com/NixOS/nix.git"; - ref = "refs/heads/0.5-release"; - } + - To fetch an arbitrary reference: + + builtins.fetchGit { + url = "https://github.com/NixOS/nix.git"; + ref = "refs/heads/0.5-release"; + } - If the revision you're looking for is in the default branch of the - git repository you don't strictly need to specify the branch name in - the `ref` attribute. + - If the revision you're looking for is in the default branch of + the git repository you don't strictly need to specify the branch + name in the `ref` attribute. + + However, if the revision you're looking for is in a future + branch for the non-default branch you will need to specify the + the `ref` attribute as well. + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + ref = "1.11-maintenance"; + } + + > **Note** + > + > It is nice to always specify the branch which a revision + > belongs to. Without the branch being specified, the fetcher + > might fail if the default branch changes. Additionally, it can + > be confusing to try a commit from a non-default branch and see + > the fetch fail. If the branch is specified the fault is much + > more obvious. - However, if the revision you're looking for is in a future branch - for the non-default branch you will need to specify the the `ref` - attribute as well. + - If the revision you're looking for is in the default branch of + the git repository you may omit the `ref` attribute. + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + } - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; - ref = "1.11-maintenance"; - } + - To fetch a specific tag: + + builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + ref = "refs/tags/1.9"; + } - > **Note** - > - > It is nice to always specify the branch which a revision belongs - > to. Without the branch being specified, the fetcher might fail if - > the default branch changes. Additionally, it can be confusing to - > try a commit from a non-default branch and see the fetch fail. If - > the branch is specified the fault is much more obvious. - - If the revision you're looking for is in the default branch of the - git repository you may omit the `ref` attribute. - - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; - } - - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - ref = "refs/tags/1.9"; - } - - `builtins.fetchGit` can behave impurely fetch the latest version of - a remote branch. - - > **Note** - > - > Nix will refetch the branch in accordance to - > [???](#conf-tarball-ttl). - - > **Note** - > - > This behavior is disabled in *Pure evaluation mode*. - - builtins.fetchGit { - url = "ssh://git@github.com/nixos/nix.git"; - ref = "master"; - } + - To fetch the latest version of a remote branch: + + builtins.fetchGit { + url = "ssh://git@github.com/nixos/nix.git"; + ref = "master"; + } + + > **Note** + > + > Nix will refetch the branch in accordance to + > [???](#conf-tarball-ttl). + + > **Note** + > + > This behavior is disabled in *Pure evaluation mode*. - `builtins.filter` f xs Return a list consisting of the elements of xs for which the diff --git a/doc/manual/src/package-management/copy-closure.md b/doc/manual/src/package-management/copy-closure.md index 6573862c0..d78b77e36 100644 --- a/doc/manual/src/package-management/copy-closure.md +++ b/doc/manual/src/package-management/copy-closure.md @@ -1,4 +1,4 @@ -# Copying Closures Via SSH +# Copying Closures via SSH The command `nix-copy-closure` copies a Nix store path along with all its dependencies to or from another machine via the SSH protocol. It diff --git a/doc/manual/src/package-management/s3-substituter.md b/doc/manual/src/package-management/s3-substituter.md index 4740b8b1c..d96114e3c 100644 --- a/doc/manual/src/package-management/s3-substituter.md +++ b/doc/manual/src/package-management/s3-substituter.md @@ -1,7 +1,7 @@ -# Serving a Nix store via AWS S3 or S3-compatible Service +# Serving a Nix store via S3 Nix has built-in support for storing and fetching store paths from -Amazon S3 and S3 compatible services. This uses the same *binary* cache +Amazon S3 and S3-compatible services. This uses the same *binary* cache mechanism that Nix usually uses to fetch prebuilt binaries from [cache.nixos.org](cache.nixos.org). @@ -124,10 +124,12 @@ Your account will need the following IAM policy to upload to the cache: ] } -`nix copy --to -'s3://example-nix-cache?profile=cache-upload®ion=eu-west-2' -nixpkgs.hello` +## Examples -`nix copy --to -'s3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' -nixpkgs.hello` +To upload with a specific credential profile for Amazon S3: + + nix copy --to 's3://example-nix-cache?profile=cache-upload®ion=eu-west-2' nixpkgs.hello + +To upload to an S3-compatible binary cache: + + nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello