Merge pull request #11 from blocklessnetwork/upd/ipfs-car-compliance

`ipfs-car` CLI compliance

README.md

@@ -1,78 +1,79 @@
 # car-utils
 
-The project is utils of CAR file which used in WASM runtime.
+The project is utils of `CAR` file which used in WASM runtime.
 
-if you wanna lean about WASM runtime, please vist "https://github.com/blocklessnetwork/runtime/".
+if you wanna lean about WASM runtime, please vist
+"https://github.com/blocklessnetwork/runtime/".
 
 ## How to intsall.
 
-use cargo install to install the command
+Use cargo install to install the CLI:
 
 ```
 cargo install car-utils
 ```
 
-car-utils install in the cargo bin directory.
+Note: car-utils installs to the cargo bin directory.
 
 ## How to use.
 
-execute the command `car-utils --help` to show the command help.
+Execute the command `car-utils --help` to show the command help.
 
 ```
+car-utils
+
 Usage: car-utils <COMMAND>
 
 Commands:
-  ar    Archive local file system to a car file
-  cat   View cid content from a car file
-  ls    List the car files
-  cid   List the car cid
-  ex    Extract the car files
-  help  Print this message or the help of the given subcommand(s)
+  pack    Pack files into a CAR
+  unpack  Unpack files and directories from a CAR
+  ls      List the car files
+  roots   List root CIDs from a CAR
+  cat     View cid content from a car file
+  help    Print this message or the help of the given subcommand(s)
 
 Options:
   -h, --help     Print help
   -V, --version  Print version
 ```
 
-###  ar subcommand
-
-archive the local directory to the car file.
+### pack command
 
 ```
-Archive local file system to a car file
+Pack files into a CAR
 
-Usage: car-utils ar -c <CAR> -s <SOURCE>
+Usage: car-utils pack [OPTIONS] -o <OUTPUT> <SOURCE>
+
+Arguments:
+  <SOURCE>  The source file or directory to be packed
 
 Options:
-  -c <CAR>         the car file for archive.
-  -s <SOURCE>      the source directory to be archived.
+      --no-wrap    Wrap the file (applies to files only).
+  -o <OUTPUT>      The car file to output.
   -h, --help       Print help
 ```
 
-###  ls subcommand
-
-list file structures in the car file.
+### unpack command
 
 ```
-List the car files
+Unpack files and directories from a CAR
 
-Usage: car-utils ls <CAR>
+Usage: car-utils unpack [OPTIONS] <CAR>
 
 Arguments:
-  <CAR>  the car file for list.
+  <CAR>  The car file to extract
 
 Options:
-  -h, --help  Print help
+  -o <OUTPUT>      Target directory to unpack car to.
+  -h, --help       Print help
 ```
 
-####  cid subcommand
-
-list file cids in the car file.
+### ls command
 
 ```
-List the car cid
+List the car files
 
-Usage: car-utils cid <CAR>
+Usage: car-utils ls <CAR>
 
 Arguments:
   <CAR>  the car file for list.
@@ -81,24 +82,21 @@ Options:
   -h, --help  Print help
 ```
 
-### ex subcommand
-
-extract the files in the car file to the target directory.
+#### roots command
 
 ```
-Extract the car files
+List root CIDs from a CAR
+
+Usage: car-utils roots <CAR>
 
-Usage: car-utils ex [OPTIONS] -c <CAR>
+Arguments:
+  <CAR>  the car file for list.
 
 Options:
-  -c <CAR>         The car file to extract
-  -t <TARGET>      Target directory to extract to
-  -h, --help       Print help
+  -h, --help  Print help
 ```
 
-####  cat subcommand
-
-cat cid content from a car file.
+#### cat command
 
 ```
 View cid content from a car file

bin/car-utils/src/main.rs

@@ -1,8 +1,8 @@
-mod archive;
 mod cat;
 mod error;
-mod extract;
 mod ls;
+mod pack;
+mod unpack;
 use clap::{Parser, Subcommand};
 
 /// The short version information for car-utils.
@@ -27,35 +27,35 @@ struct Cli {
 /// Commands to be executed
 #[derive(Debug, Subcommand)]
 pub enum Commands {
-    /// Archive local file system to a car file
-    #[command(name = "ar")]
-    Archive(archive::ArchiveCommand),
+    /// Pack files into a CAR.
+    #[command(name = "pack", alias = "p")]
+    Pack(pack::PackCommand),
 
-    /// View cid content from a car file
-    #[command(name = "cat")]
-    Cat(cat::CatCommand),
+    /// Unpack files and directories from a CAR.
+    #[command(name = "unpack", alias = "un")]
+    Unpack(unpack::UnpackCommand),
 
-    /// List the car files
+    /// List the car files.
     #[command(name = "ls")]
     Ls(ls::LsCommand),
 
-    /// List the car cid
-    #[command(name = "cid")]
-    Cid(ls::LsCommand),
+    /// List root CIDs from a CAR.
+    #[command(name = "roots")]
+    Roots(ls::LsCommand),
 
-    /// Extract the car files
-    #[command(name = "ex")]
-    Ex(extract::ExCommand),
+    /// View cid content from a car file.
+    #[command(name = "cat")]
+    Cat(cat::CatCommand),
 }
 
 fn main() {
     let opt = Cli::parse();
     if let Err(err) = match opt.command {
-        Commands::Archive(command) => command.execute(),
-        Commands::Cat(command) => command.execute(),
+        Commands::Pack(command) => command.execute(),
+        Commands::Unpack(command) => command.execute(),
         Commands::Ls(command) => command.execute(false),
-        Commands::Cid(command) => command.execute(true),
-        Commands::Ex(command) => command.execute(),
+        Commands::Roots(command) => command.execute(true),
+        Commands::Cat(command) => command.execute(),
     } {
         eprintln!("Error: {err:?}");
         std::process::exit(1);

bin/car-utils/src/archive.rs → bin/car-utils/src/pack.rs

@@ -3,23 +3,27 @@ use blockless_car::utils::archive_local;
 use std::path::Path;
 
 #[derive(Debug, clap::Parser)]
-pub struct ArchiveCommand {
-    #[clap(short, help = "the source directory to be archived.")]
+pub struct PackCommand {
+    /// The source file or directory to be packed.
     source: String,
 
-    #[clap(help = "wrap the file (applies to files only).", default_value = "false", long = "no-wrap")]
+    #[clap(
+        help = "Wrap the file (applies to files only).",
+        default_value = "false",
+        long = "no-wrap"
+    )]
     no_wrap_file: bool,
 
-    #[clap(short, help = "the car file for archive.")]
-    car: String,
+    #[clap(short, help = "The car file to output.")]
+    output: String,
 }
 
-impl ArchiveCommand {
+impl PackCommand {
     /// archive the local file system to car file
     /// `target` is the car file
     /// `source` is the directory where the archive is prepared.
     pub(crate) fn execute(&self) -> Result<(), UtilError> {
-        let file = std::fs::File::create(self.car.as_ref() as &Path).unwrap(); // todo handle error
+        let file = std::fs::File::create(self.output.as_ref() as &Path).unwrap(); // todo handle error
         archive_local(self.source.as_ref() as &Path, file, self.no_wrap_file)?;
         Ok(())
     }

bin/car-utils/src/extract.rs → bin/car-utils/src/unpack.rs

@@ -5,15 +5,15 @@ use blockless_car::reader::{self as car_reader, CarReader};
 use blockless_car::utils::extract_ipld;
 
 #[derive(Debug, clap::Parser)]
-pub struct ExCommand {
-    #[clap(short, help = "The car file to extract")]
+pub struct UnpackCommand {
+    /// The car file to extract.
     car: String,
 
-    #[clap(short, help = "Target directory to extract to")]
-    target: Option<String>,
+    #[clap(short, help = "Target directory to unpack car to.")]
+    output: Option<String>,
 }
 
-impl ExCommand {
+impl UnpackCommand {
     /// extract car file to local file system.
     /// `car` the car file to extract.
     /// `target` target directory to extract.
@@ -29,7 +29,7 @@ impl ExCommand {
         let mut reader = car_reader::new_v1(file)?;
         let roots = reader.header().roots();
         for cid in roots {
-            let target: Option<&Path> = self.target.as_ref().map(|s| s.as_ref());
+            let target: Option<&Path> = self.output.as_ref().map(|s| s.as_ref());
             extract_ipld(&mut reader, cid, target)?;
         }
         Ok(())

crates/blockless-car/examples/cat_file.rs → crates/blockless-car/examples/cat.rs

@@ -4,7 +4,7 @@ use blockless_car::{
 };
 
 /// Cat the file in car file by file id
-/// e.g. ```cargo run -p blockless-car --example cat_file file name.```
+/// e.g. ```cargo run -p blockless-car --example cat `file name````
 /// the example cat used file is carv1-basic.car
 fn main() {
     let file_name = std::env::args().nth(1).expect("use filename as argument");

crates/blockless-car/examples/ls.rs

@@ -1,6 +1,6 @@
 use blockless_car::reader;
 
-/// e.g. ```cargo run -p blockless-car --example ls file```
+/// e.g. ```cargo run -p blockless-car --example ls <source-car-file>```
 /// the example list file infomation in carv1-basic.car file
 fn main() {
     let file_name = std::env::args().nth(1);

crates/blockless-car/examples/archive.rs → crates/blockless-car/examples/pack.rs

@@ -1,7 +1,7 @@
 use blockless_car::utils::archive_local;
 
 /// Cat the file in car file by file id
-/// e.g. ```cargo run -p blockless-car --example `archive directory` `target car file`.```
+/// e.g. ```cargo run -p blockless-car --example pack <target-car-file>```
 fn main() {
     let file_name = std::env::args().nth(1).expect("use directory as argument");
     let target = std::env::args()

crates/blockless-car/examples/cat_cid.rs → crates/blockless-car/examples/roots.rs

@@ -7,7 +7,7 @@ use blockless_car::{
 use cid::Cid;
 
 /// Cat the file in car file by file id
-/// e.g. ```cargo run -p blockless-car --example cat_file bafkreiabltrd5zm73pvi7plq25pef3hm7jxhbi3kv4hapegrkfpkqtkbme```
+/// e.g. ```cargo run -p blockless-car --example roots bafkreiabltrd5zm73pvi7plq25pef3hm7jxhbi3kv4hapegrkfpkqtkbme```
 /// the example cat file with cid in carv1-basic.car
 fn main() {
     // let cid = std::env::args().nth(1).expect("use cid as argument");

crates/blockless-car/examples/extract.rs → crates/blockless-car/examples/unpack.rs

@@ -4,7 +4,7 @@ use blockless_car::{
 };
 
 /// extract all files in car file by file id
-/// e.g. ```cargo run -p blockless-car --example extract```
+/// e.g. ```cargo run -p blockless-car --example unpack <source-car-file>```
 /// the example cat used file is carv1-basic.car
 fn main() {
     let file_name = std::env::args().nth(1);