feat: use psvm from ref

README.md

@@ -24,6 +24,8 @@ If you want to update the local dependencies (using `path="..."`), you can use t
 
 If you want to update the dependencies to a specific Polkadot SDK version, you can use the `-v` or `--version` flag, followed by the version you want to update to.
 
+If you need to point at a specific git branch or tag (for example an unstable tag), use `--ref` with the branch/tag name that contains the release metadata. `--ref` is an alternative to `--version`; they cannot be used together.
+
 If you want to check if the dependencies in your local Cargo.toml file are matching to a specific Polkadot SDK version, you can use the `-c` or `--check` flag along with the `--version` flag followed by the version you want to check against.
 
 If you want to update the ORML crates in your local Cargo.toml, you can use the `-O` or `--orml` flag along with the `--version` flag to update the ORML crates along with the polkadot-sdk crates. This works only if the supplied version is present in the ORML releases.
@@ -37,6 +39,8 @@ psvm -v "1.3.0"
 psvm -v "1.4.0" -p <cargo-toml-dir>/Cargo.toml
 # Overwrite local dependencies (with same name as Polkadot SDK crates) with crates.io versions
 psvm -v "1.7.0" -o
+# Use a specific git branch or tag that already includes Plan.toml/Cargo.lock
+psvm --ref polkadot-unstable2507-revive
 # List all available Polkadot SDK versions
 psvm -l
 # Check against a particular Polkadot SDK version without updating the Cargo.toml file

src/main.rs

@@ -34,7 +34,12 @@ struct Command {
     path: PathBuf,
 
     /// Specifies the Polkadot SDK version. Use '--list' flag to display available versions.
-    #[clap(short, long, required_unless_present = "list")]
+    #[clap(
+        short,
+        long,
+        required_unless_present_any = ["list", "git_ref"],
+        conflicts_with = "git_ref"
+    )]
     version: Option<String>,
 
     /// Overwrite local dependencies (using path) with same name as the ones in the Polkadot SDK.
@@ -50,8 +55,12 @@ struct Command {
     check: bool,
 
     /// To either list available ORML versions or update the Cargo.toml file with corresponding ORML versions.
-    #[clap(short('O'), long)]
+    #[clap(short('O'), long, requires = "version")]
     orml: bool,
+
+    /// Explicit git reference (branch or tag) to fetch release metadata from.
+    #[clap(long = "ref", conflicts_with = "version")]
+    git_ref: Option<String>,
 }
 
 #[tokio::main]
@@ -73,16 +82,24 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         return Ok(());
     }
 
-    let version = cmd.version.unwrap(); // Safe to unwrap due to `required_unless_present`
+    let version_or_ref = cmd
+        .version
+        .as_deref()
+        .or(cmd.git_ref.as_deref())
+        .expect("clap enforces presence of either version or git_ref");
 
     let cargo_toml_path = validate_workspace_path(cmd.path)?;
 
     // Decide which branch data to use based on the branch name
     let mut crates_versions: BTreeMap<String, String> =
-        get_version_mapping_with_fallback(DEFAULT_GIT_SERVER, &version).await?;
+        get_version_mapping_with_fallback(DEFAULT_GIT_SERVER, version_or_ref).await?;
 
     if cmd.orml {
-        let orml_crates = get_orml_crates_and_version(DEFAULT_GIT_SERVER, &version).await?;
+        let version = cmd
+            .version
+            .as_deref()
+            .expect("ORML lookups require a version");
+        let orml_crates = get_orml_crates_and_version(DEFAULT_GIT_SERVER, version).await?;
         include_orml_crates_in_version_mapping(&mut crates_versions, orml_crates);
     }
 

src/tests.rs

@@ -300,6 +300,35 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
         assert_eq!(mapping.get("local_package"), Some(&"0.1.0".to_string()));
     }
 
+    #[tokio::test]
+    async fn test_explicit_git_ref_is_used() {
+        let response = r#"
+[[crate]]
+name = "package_minor"
+from = "0.1.0"
+to = "0.2.0"
+"#;
+        let git_ref = "polkadot-unstable-custom";
+        let source = "Plan.toml";
+
+        let mut server = mockito::Server::new_async().await;
+        let _m = server
+            .mock(
+                "GET",
+                format!("/paritytech/polkadot-sdk/{}/{}", git_ref, source).as_str(),
+            )
+            .with_status(200)
+            .with_body(response)
+            .create();
+
+        let mapping = get_version_mapping_with_fallback(&server.url(), git_ref)
+            .await
+            .unwrap();
+
+        assert_eq!(mapping.len(), 1);
+        assert_eq!(mapping.get("package_minor"), Some(&"0.2.0".to_string()));
+    }
+
     #[tokio::test]
     // This test will fetch all available versions, update a generic parachain Cargo.toml file
     // and assert that the Cargo.toml file has been updated (modified)

src/versions.rs

@@ -317,6 +317,8 @@ fn version_to_url(base_url: &str, version: &str, source: &str) -> String {
         format!("polkadot-{}", version)
     } else if stable_tag_regex_patten.is_match(version) {
         version.into()
+    } else if version.starts_with("polkadot-unstable") {
+        version.into()
     } else {
         format!("release-crates-io-v{}", version)
     };