Merge pull request #162 from DeterminateSystems/fh-fetch-release

Prepare `fh fetch` release

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fh"
-version = "0.1.21"
+version = "0.1.22"
 authors = ["Determinate Systems <[email protected]>"]
 edition = "2021"
 license = "Apache 2.0"

README.md

@@ -52,6 +52,7 @@ You can use fh to:
 - [Check FlakeHub login status](#check-flakehub-login-status)
 - [Initialize a new `flake.nix`](#initialize-a-new-flakenix-from-scratch)
 - [Add flake inputs to your `flake.nix`](#add-a-flake-published-to-flakehub-to-your-flakenix)
+- [Fetch flake outputs directly from FlakeHub Cache](#fetch-flake-outputs-directly)
 - [Resolve flake references to store paths](#resolve-flake-references-to-store-paths)
 - [Apply NixOS, Home Manager, and nix-darwin configurations to the current system](#apply-configurations-to-the-current-system)
 - [Convert flake inputs to use FlakeHub](#convert-flake-inputs-to-use-flakehub)
@@ -136,6 +137,25 @@ The resulting `flake.nix` would look something like this:
 }
 ```
 
+### Fetch flake outputs directly
+
+You can fetch [flake outputs][outputs] directly from FlakeHub using the `fh fetch` command.
+You need to specify both a [flake reference][flakeref] and the target link to which fh should write the symlink to the output's [Nix store path][store-paths].
+
+Here's an example:
+
+```shell
+# Fetch the output for the current system
+SYSTEM="$(nix eval --impure --expr 'builtins.currentSystem' --raw)"
+fh fetch "DeterminateSystems/fh/*#packages.${SYSTEM}.default" ./out
+
+# Run the fh executable using the target link
+./out/bin/fh --help
+```
+
+`fh fetch` is most useful when used in conjunction with [FlakeHub Cache][cache], which is available on FlakeHub [paid plans][signup].
+If the flake output is stored in the cache, `fh fetch` can fetch the cached output without needing to evaluate the store path, which is [also stored][resolved-store-paths] in the cache.
+
 ### Resolve flake references to store paths
 
 You can resolve flake references on FlakeHub to Nix store paths using the `fh resolve` command:
@@ -460,14 +480,15 @@ You can apply the `--json` flag to each list command to produce JSON output.
 For support, email [email protected] or [join our Discord](https://discord.gg/invite/a4EcQQ8STr).
 
 [bash]: https://gnu.org/software/bash
-[cache]: https://determinate.systems/posts/flakehub-cache-beta
+[cache]: https://flakehub.com/cache
 [csv]: https://en.wikipedia.org/wiki/Comma-separated_values
 [elm]: https://elm-lang.org
 [elvish]: https://elv.sh
 [fish]: https://fishshell.com
 [flakehub]: https://flakehub.com
 [flakehub-push]: https://github.com/determinateSystems/flakehub-push
 [flakehub-push-params]: https://github.com/determinateSystems/flakehub-push?tab=readme-ov-file#available-parameters
+[flakeref]: https://zero-to-nix.com/concepts/flakes#references
 [flakes]: https://flakehub.com/flakes
 [go]: https://golang.org
 [hm]: https://github.com/nix-community/home-manager
@@ -479,13 +500,17 @@ For support, email [email protected] or [join our Discord](https://discord.gg
 [nixos]: https://zero-to-nix.com/concepts/nixos
 [nixpkgs]: https://zero-to-nix.com/concepts/nixpkgs
 [orgs]: https://flakehub.com/orgs
+[outputs]: https://zero-to-nix.com/concepts/flakes#outputs
 [php]: https://php.net
 [powershell]: https://learn.microsoft.com/powershell
 [python]: https://python.org
+[resolved-store-paths]: https://docs.determinate.systems/flakehub/store-paths
 [ruby]: https://ruby-lang.org
 [rust]: https://rust-lang.org
 [semver]: https://flakehub.com/docs/concepts/semver
 [settings]: https://flakehub.com/user/settings
+[signup]: https://flakehub.com/signup
+[store-paths]: https://zero-to-nix.com/concepts/nix-store#store-paths
 [tokens]: https://flakehub.com/user/settings?editview=tokens
 [zig]: https://ziglang.org
 [zsh]: https://zsh.org

src/cli/cmd/fetch.rs

@@ -9,14 +9,15 @@ use crate::shared::create_temp_netrc;
 
 use super::{CommandExecute, FlakeHubClient};
 
+/// Fetch a flake output and write a symlink for the Nix store path to the target link
 #[derive(Parser)]
 pub(crate) struct FetchSubcommand {
-    /// The FlakeHub flake reference to fetch.
+    /// The flake reference for the FlakeHub flake output to fetch.
     /// References must be of this form: {org}/{flake}/{version_req}#{attr_path}
     flake_ref: String,
 
-    /// Target link to use as a Nix garbage collector root
-    target: String,
+    /// The target link to use as a Nix garbage collector root
+    target_link: String,
 
     #[clap(from_global)]
     api_addr: url::Url,
@@ -60,11 +61,15 @@ impl CommandExecute for FetchSubcommand {
             self.cache_addr.as_str(),
             &resolved_path.store_path,
             token_path,
-            &self.target,
+            &self.target_link,
         )
         .await?;
 
-        tracing::info!("Copied {} to {}", resolved_path.store_path, self.target);
+        tracing::info!(
+            "Copied {} to {}",
+            resolved_path.store_path,
+            self.target_link
+        );
 
         dir.close()?;