lix-project/lix
19
52
Fork 27
Code Issues 341 Code Review (Gerrit) Projects 2 Releases Wiki Activity

Get rid of <example>

Browse source 
Markdown doesn't have floats so we can't have this.
This commit is contained in:
Eelco Dolstra 2020-07-23 14:10:59 +02:00
parent 13df1faf25
commit ca130b73a0
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
6 changed files with 156 additions and 134 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

117
doc/manual/expressions/builtins.xml
View file

@ -434,88 +434,93 @@ stdenv.mkDerivation { … }
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<example> <para>Here are some examples of how to use
<title>Fetching a private repository over SSH</title> <literal>fetchGit</literal>.</para>
<programlisting>builtins.fetchGit {
<itemizedlist>
<listitem>
<para>To fetch a private repository over SSH:</para>
<programlisting>builtins.fetchGit {
url = "git@github.com:my-secret/repository.git"; url = "git@github.com:my-secret/repository.git";
ref = "master"; ref = "master";
rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
}</programlisting> }</programlisting>
</example>
<example> </listitem>
<title>Fetching an arbitrary ref</title>
<programlisting>builtins.fetchGit { <listitem>
<para>To fetch an arbitrary reference:</para>
<programlisting>builtins.fetchGit {
url = "https://github.com/NixOS/nix.git"; url = "https://github.com/NixOS/nix.git";
ref = "refs/heads/0.5-release"; ref = "refs/heads/0.5-release";
}</programlisting> }</programlisting>
</example> </listitem>
<example> <listitem>
<title>Fetching a repository's specific commit on an arbitrary branch</title> <para>
<para> If the revision you're looking for is in the default branch
If the revision you're looking for is in the default branch of the git repository you don't strictly need to specify
of the git repository you don't strictly need to specify the branch name in the <varname>ref</varname> attribute.
the branch name in the <varname>ref</varname> attribute. </para>
</para> <para>
<para> However, if the revision you're looking for is in a future
However, if the revision you're looking for is in a future branch for the non-default branch you will need to specify
branch for the non-default branch you will need to specify the the <varname>ref</varname> attribute as well.
the the <varname>ref</varname> attribute as well. </para>
</para>
<programlisting>builtins.fetchGit { <programlisting>builtins.fetchGit {
url = "https://github.com/nixos/nix.git"; url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
ref = "1.11-maintenance"; ref = "1.11-maintenance";
}</programlisting> }</programlisting>
<note>
<para>
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.
</para>
</note>
</example>
<example> <note>
<title>Fetching a repository's specific commit on the default branch</title> <para>
<para> It is nice to always specify the branch which a revision
If the revision you're looking for is in the default branch belongs to. Without the branch being specified, the
of the git repository you may omit the fetcher might fail if the default branch changes.
<varname>ref</varname> attribute. Additionally, it can be confusing to try a commit from a
</para> non-default branch and see the fetch fail. If the branch
<programlisting>builtins.fetchGit { is specified the fault is much more obvious.
</para>
</note>
</listitem>
<listitem>
<para>
If the revision you're looking for is in the default branch
of the git repository you may omit the
<varname>ref</varname> attribute.
</para>
<programlisting>builtins.fetchGit {
url = "https://github.com/nixos/nix.git"; url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
}</programlisting> }</programlisting>
</example> </listitem>
<example> <listitem>
<title>Fetching a tag</title> <para>To fetch a specific tag:</para>
<programlisting>builtins.fetchGit { <programlisting>builtins.fetchGit {
url = "https://github.com/nixos/nix.git"; url = "https://github.com/nixos/nix.git";
ref = "refs/tags/1.9"; ref = "refs/tags/1.9";
}</programlisting> }</programlisting>
</example> </listitem>
<example> <listitem>
<title>Fetching the latest version of a remote branch</title> <para>To fetch the latest version of a remote branch:</para>
<para>
<function>builtins.fetchGit</function> can behave impurely
fetch the latest version of a remote branch.
</para>
<note><para>Nix will refetch the branch in accordance to
<xref linkend="conf-tarball-ttl" />.</para></note>
<note><para>This behavior is disabled in
<emphasis>Pure evaluation mode</emphasis>.</para></note>
<programlisting>builtins.fetchGit { <programlisting>builtins.fetchGit {
url = "ssh://git@github.com/nixos/nix.git"; url = "ssh://git@github.com/nixos/nix.git";
ref = "master"; ref = "master";
}</programlisting> }</programlisting>
</example> <note><para>Nix will refetch the branch in accordance to
<xref linkend="conf-tarball-ttl" />.</para></note>
<note><para>This behavior is disabled in <emphasis>Pure
evaluation mode</emphasis>.</para></note>
</listitem>
</itemizedlist>
</listitem> </listitem>
</varlistentry> </varlistentry>

2
doc/manual/packages/copy-closure.xml
View file

@ -4,7 +4,7 @@
version="5.0" version="5.0"
xml:id="ssec-copy-closure"> xml:id="ssec-copy-closure">
<title>Copying Closures Via SSH</title> <title>Copying Closures via SSH</title>
<para>The command <command <para>The command <command
linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix

29
doc/manual/packages/s3-substituter.xml
View file

@ -5,10 +5,10 @@
version="5.0" version="5.0"
xml:id="ssec-s3-substituter"> xml:id="ssec-s3-substituter">
<title>Serving a Nix store via AWS S3 or S3-compatible Service</title> <title>Serving a Nix store via S3</title>
<para>Nix has built-in support for storing and fetching store paths <para>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
<emphasis>binary</emphasis> cache mechanism that Nix usually uses to <emphasis>binary</emphasis> cache mechanism that Nix usually uses to
fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para> fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para>
@ -170,13 +170,22 @@ the S3 URL:</para>
} }
]]></programlisting> ]]></programlisting>
<example><title>Uploading with a specific credential profile for Amazon S3</title>
<para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;region=eu-west-2' nixpkgs.hello</command></para>
</example>
<example><title>Uploading to an S3-Compatible Binary Cache</title>
<para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;scheme=https&amp;endpoint=minio.example.com' nixpkgs.hello</command></para>
</example>
</section> </section>
<section><title>Examples</title>
<para>To upload with a specific credential profile for Amazon S3:</para>
<screen>
nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;region=eu-west-2' nixpkgs.hello
</screen>
<para>To upload to an S3-compatible binary cache:</para>
<screen>
nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;scheme=https&amp;endpoint=minio.example.com' nixpkgs.hello
</screen>
</section>
</section> </section>

122
doc/manual/src/expressions/builtins.md
View file

@ -169,70 +169,76 @@ For instance, `derivation` is also available as `builtins.derivation`.
A Boolean parameter that specifies whether submodules should be A Boolean parameter that specifies whether submodules should be
checked out. Defaults to `false`. checked out. Defaults to `false`.
<!-- end list --> Here are some examples of how to use `fetchGit`.
builtins.fetchGit { - To fetch a private repository over SSH:
url = "git@github.com:my-secret/repository.git";
ref = "master"; builtins.fetchGit {
rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; url = "git@github.com:my-secret/repository.git";
} ref = "master";
rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
}
builtins.fetchGit { - To fetch an arbitrary reference:
url = "https://github.com/NixOS/nix.git";
ref = "refs/heads/0.5-release"; 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 - If the revision you're looking for is in the default branch of
git repository you don't strictly need to specify the branch name in the git repository you don't strictly need to specify the branch
the `ref` attribute. 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 - If the revision you're looking for is in the default branch of
for the non-default branch you will need to specify the the `ref` the git repository you may omit the `ref` attribute.
attribute as well.
builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
}
builtins.fetchGit { - To fetch a specific tag:
url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; builtins.fetchGit {
ref = "1.11-maintenance"; url = "https://github.com/nixos/nix.git";
} ref = "refs/tags/1.9";
}
> **Note** - To fetch the latest version of a remote branch:
>
> It is nice to always specify the branch which a revision belongs builtins.fetchGit {
> to. Without the branch being specified, the fetcher might fail if url = "ssh://git@github.com/nixos/nix.git";
> the default branch changes. Additionally, it can be confusing to ref = "master";
> try a commit from a non-default branch and see the fetch fail. If }
> the branch is specified the fault is much more obvious.
> **Note**
If the revision you're looking for is in the default branch of the >
git repository you may omit the `ref` attribute. > Nix will refetch the branch in accordance to
> [???](#conf-tarball-ttl).
builtins.fetchGit {
url = "https://github.com/nixos/nix.git"; > **Note**
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; >
} > This behavior is disabled in *Pure evaluation mode*.
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";
}
- `builtins.filter` f xs - `builtins.filter` f xs
Return a list consisting of the elements of xs for which the Return a list consisting of the elements of xs for which the

2
doc/manual/src/package-management/copy-closure.md
View file

@ -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 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 its dependencies to or from another machine via the SSH protocol. It

18
doc/manual/src/package-management/s3-substituter.md
View file

@ -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 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 mechanism that Nix usually uses to fetch prebuilt binaries from
[cache.nixos.org](cache.nixos.org). [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 ## Examples
's3://example-nix-cache?profile=cache-upload&region=eu-west-2'
nixpkgs.hello`
`nix copy --to To upload with a specific credential profile for Amazon S3:
's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com'
nixpkgs.hello` 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