Improved desc. in README, explain why tool exists

Barely anything has changed, but the package *is* different. v3 is from
months back and is missing information that Crates.io kinda wants.

.gitea/workflows/release.yml

@@ -22,7 +22,9 @@ jobs:
       - name: Upload the program (using itself!)
         run: >
           target/release/gt-tool-${{ github.ref_name }}-$(arch)
-          -u ${{ vars.DEST_GITEA }} -r ${{ vars.DEST_REPO }}
+          -u ${{ vars.DEST_GITEA }}
+          -o ${{ vars.DEST_OWNER }}
+          -r ${{ vars.DEST_REPO }}
           upload-release
           "${{ github.ref_name }}"
           target/release/gt-tool-${{ github.ref_name }}-$(arch)

Cargo.toml

@@ -1,23 +1,18 @@
 [package]
 name = "gt-tool"
-version = "3.0.0-alpha.1"
+version = "3.0.1"
 edition = "2024"
+license = "GPL-3.0-only"
+description = "CLI tools for interacting with the Gitea API. Mainly for attaching files to releases."
+# homepage = "" I have no website for a project home page :(
+repository = "https://git.gelvin.dev/robert/gt-tool"
+readme = "README.md"
 
 [dependencies]
-clap = { version = "4.0.7", features = ["derive", "env"] }
-colored = "2.0.0"
-itertools = "0.10.0"
-reqwest = { version = "0.11.13", features = ["json", "stream", "multipart"] }
-serde = { version = "1.0.152", features = ["derive"] }
-tokio = { version = "1.24.2", features = ["macros", "rt-multi-thread"] }
-toml = "0.5"
-
-# Packages available in Debian (Sid)
-# clap = "4.5.23"
-# reqwest = "0.12.15"
-# tokio = "1.43.1"
-
-# Debian (Bookworm)
-# clap = "4.0.32"
-# reqwest = "0.11.13"
-# tokio = "1.24.2"
+clap = { version = "4.5.23", features = ["derive", "env"] }
+colored = "2.2.0"
+itertools = "0.13.0"
+reqwest = { version = "0.12.15", features = ["json", "stream", "multipart"] }
+serde = { version = "1.0.217", features = ["derive"] }
+tokio = { version = "1.43.1", features = ["macros", "rt-multi-thread"] }
+toml = "0.8.19"

README.md

@@ -1,6 +1,12 @@
 # gt-tool
 
-CLI tools for interacting with the Gitea API. Use interactively to talk to your Gitea instance, or automatically via a CI/CD pipeline.
+A CLI tool for interacting with the Gitea API. List existing releases, create new ones, and attach release-items (files) to them. It can be used interactively as one publishes their work, or automatically as part of a CI/CD pipeline.
+
+## Why this thing exists
+
+This program exists because I find GitHub Actions to be an insufficient system. There is no official "release-attachment" workflow. I have to either make my own or find someone else's. Since there is no standard Workflow for this task, the [Gitea version](https://gitea.com/actions/gitea-release-action) has a different API. Since I can only use branches, tags, or exact commit hashes, my dependency resolution is often manual or happens in surprising ways (e.g.: force pushing a new version tag). Adjacent to this is the issue that lots of dependencies are "assumed" and cannot be named -- like how the Ubuntu base image contains NodeJS, even if I never ask to install it. Finally, I can't easily execute or re-execute the workflows. There is no "run Action" button and I can't run any of it from my dev machine.
+
+So I figured I'll make my own as a learning exercise and try to address as many of those problems as I can. The key is recognizing that a CI/CD platform needs a package manager. I like Debian, so I will stand on its package manager, although it might be better to pick NixOS or Gentoo. A GH Workflow which depends on this tool needs only to record it's name -- declarative build dependencies! This feature extends to the entire Debian container, automatically giving me full-system dependency knowledge. Updating the build environment is exactly like updating a normal Linux host because it *is* a normal Linux host. Lastly, it's also *a normal CLI program* so you can use it from your own dev workstation. There is no need for a "run Action" button.
 
 ## Usage
 
@@ -15,41 +21,51 @@ Commands:
 
 Options:
   -u, --url <GITEA_URL>    [env: GTTOOL_GITEA_URL=]
-  -r, --repo <REPO>        [env: GTTOOL_FQRN=]
-  -p, --project <PROJECT>  Path to project (relative or absolute). Used to select configuration.
+  -o, --owner <OWNER>      [env: GTTOOL_OWNER=]
+  -r, --repo <REPO>        [env: GTTOOL_REPO=]
+  -p, --project <PROJECT>  Path to project (relative or absolute). Used to override configuration selection.
   -h, --help               Print help
   -V, --version            Print version
 ```
 
+### Required Information
+
+To function, this program requires knowledge of these items:
+
+- Gitea URL
+- Owner of repository
+- Repository name
+
+This info will be gathered from these locations, in order of priority:
+
+1. CLI argument
+2. Environment variable
+3. Configuration files
+
+It's worth noting that the "owner" is the entity that controls the repo on the Gitea instance. This will be the first part of the route in the URL: `http://demo.gitea.com/{owner}`.
+
+Likewise, the "repo" is what ever the Gitea instance thinks it's called -- which doesn't have to match anyone's local copy! It will be the second part of the route in the URL: `http://demo.gitea.com/{owner}/{repo}`.
+
 ### Authentication
 
-Authentication is token-based via environment variable `RELEASE_KEY_GITEA`.
+Authentication is token-based. There is no CLI option to prevent the token from appearing in any command logs.
 
-Ensure your token has the appropriate access for your usage. This depends on what you're doing and how your Gitea instance is configured, so you'll have to figure it out for yourself.
+In order of priority, the token is loaded from:
 
-Most likely, you will need a token with "repository: read-and-write" permissions. See Gitea's documentation on [token scopes](https://docs.gitea.com/development/oauth2-provider#scopes) for more.
+1. The environment variable `RELEASE_KEY_GITEA`
+2. Config files, key `token`
 
-### `<GITEA_URL>`:
+Whether or not it is required depends on how your Gitea instance and the repositories inside are configured.  For example, a default Gitea configuration will allow unauthenticated users to see public repositories but not make any changes. This means no token is required to run `gt-tool list-releases`, while `gt-tool upload-release` *will* require a token.
 
-The Gitea server URL must be provided with `--url` or `-u` on the command line, or via the environment variable `GTTOOL_GITEA_URL`. Use the base URL for your Gitea instance.
+For details, see Gitea's documentation on [token scopes](https://docs.gitea.com/development/oauth2-provider#scopes).
 
-E.g.: Using the Gitea org's demo instance, it would be: `--url "https://demo.gitea.com/"`
+### The `--project` option
 
-### `<REPO>`:
-
-The repository name must be provided with `--repo` or `-u` on the command line, or via the environment variable `GTTOOL_GITEA_FQRN` ("fully qualified repo name"). Use the format `<owner>/<repo>`, which is the route immediately following the GITEA_URL base. This is how GitHub and Gitea identify repos in the URL, and how Golang locates it's modules, so this tool does the same.
-
-E.g.: `--repo "go-gitea/gitea"` would name the Gitea repo belonging to the go-gitea organization.
-
-### `<PROJECT>`
-
-Override the default (current-directory) project name when searching through the config files for this project's settings.
+Settings retrieved from config files are selected based on the project's path. By default, the current directory will be used. In case that guess is incorrect, this option can be specified with another path.
 
 See [configuration](#configuration) for details on format and file locations.
 
-### `<COMMAND>`:
-
-One of these, defaults to `help`:
+### Commands:
 
 | Command | Description |
 |-|-|
@@ -64,6 +80,8 @@ Instead of specifying everything on the command line every single run, some TOML
 
 > Exporting some environment variables would be similar, but that would be *more* annoying when working on multiple projects. One would have to constantly re-export the settings or use two shells. But then there's the issue of losing track of which shell has which settings.
 
+### File Format
+
 Settings are retrieved from a table named the same as the project's path on disk. For example, gt_tool itself could have an entry as follows:
 
 ```toml
@@ -74,7 +92,7 @@ repo = "gt-tool"
 token = "fake-token"
 ```
 
-Some may apply to all projects. For this, one can use the special `[all]` table.
+Sometimes one may want to apply a setting to all projects. For this, they can use the special `[all]` table.
 
 ```toml
 [all]
@@ -87,7 +105,6 @@ Since the more-specific settings are preferred, these can be combined to have an
 [all]
 gitea_url = "https://demo.gitea.com/"
 owner = "robert"
-# no `repo = ` section because that must be project specific.
 token = "fake-token"
 
 # Override Gitea target so I can test my uploads privately.
@@ -96,7 +113,12 @@ gitea_url = "http://localhost:3000"
 repo = "gt-tool"
 ```
 
-Similar to how unspecified project settings will fall back to those in the "`[all]`" table, whole files will fall back to other, lower priority files. First, each dir in `$XDG_CONFIG_DIRS` is scanned for a `gt-tool.toml` file. Then, `/etc/gt-tool.toml`.
+### Search Paths
+
+Similar to how unspecified project settings will fall back to those in the "`[all]`" table, whole files will fall back to other, lower priority files.
+
+1. First, each dir in `$XDG_CONFIG_DIRS` is scanned for a `gt-tool.toml` file.
+2. Then, `/etc/gt-tool.toml`.
 
 > All config files **MUST** be named named `gt-tool.toml`.
 

src/main.rs

@@ -31,16 +31,18 @@ async fn main() -> Result<(), gt_tool::Error> {
         .or(config.gitea_url)
         .ok_or(gt_tool::Error::MissingGiteaUrl)?;
 
-    let owner = args.owner
+    let owner = args
+        .owner
         .or(config.owner)
         .ok_or(gt_tool::Error::MissingRepoOwner)?;
 
-    let repo = args.repo
+    let repo = args
+        .repo
         .or(config.repo)
         .or_else(infer_repo)
         .ok_or(gt_tool::Error::MissingRepoName)?;
 
-    let repo_fqrn = String::from(format!("{owner}/{repo}"));
+    let repo_fqrn = format!("{owner}/{repo}");
 
     let mut headers = reqwest::header::HeaderMap::new();
     headers.append(ACCEPT, header::HeaderValue::from_static("application/json"));