Update the readme with direct upload details (#795)

* Update the readme with direct upload details

* Update the TOC and remove a section

* Fix some wording

* Remove a tautology

README.md

@@ -11,15 +11,14 @@ Upload [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/st
 See also [download-artifact](https://github.com/actions/download-artifact).
 
 - [`@actions/upload-artifact`](#actionsupload-artifact)
-  - [v6 - What's new](#v6---whats-new)
-  - [v4 - What's new](#v4---whats-new)
-    - [Improvements](#improvements)
-    - [Breaking Changes](#breaking-changes)
+  - [What's new](#whats-new)
+  - [GHES Support](#ghes-support)
   - [Usage](#usage)
     - [Inputs](#inputs)
     - [Outputs](#outputs)
   - [Examples](#examples)
-    - [Upload an Individual File](#upload-an-individual-file)
+    - [Upload an Individual File (Zipped)](#upload-an-individual-file-zipped)
+    - [Upload an Individual File (Unzipped)](#upload-an-individual-file-unzipped)
     - [Upload an Entire Directory](#upload-an-entire-directory)
     - [Upload using a Wildcard Pattern](#upload-using-a-wildcard-pattern)
     - [Upload using Multiple Paths and Exclusions](#upload-using-multiple-paths-and-exclusions)
@@ -34,49 +33,12 @@ See also [download-artifact](https://github.com/actions/download-artifact).
     - [Overwriting an Artifact](#overwriting-an-artifact)
   - [Limitations](#limitations)
     - [Number of Artifacts](#number-of-artifacts)
-    - [Zip archives](#zip-archives)
     - [Permission Loss](#permission-loss)
   - [Where does the upload go?](#where-does-the-upload-go)
 
+## What's new
 
-## v6 - What's new
-
-> [!IMPORTANT]
-> actions/upload-artifact@v6 now runs on Node.js 24 (`runs.using: node24`) and requires a minimum Actions Runner version of 2.327.1. If you are using self-hosted runners, ensure they are updated before upgrading.
-
-### Node.js 24
-
-This release updates the runtime to Node.js 24. v5 had preliminary support for Node.js 24, however this action was by default still running on Node.js 20. Now this action by default will run on Node.js 24.
-
-## v4 - What's new
-
-> [!IMPORTANT]
-> upload-artifact@v4+ is not currently supported on GitHub Enterprise Server (GHES) yet. If you are on GHES, you must use [v3](https://github.com/actions/upload-artifact/releases/tag/v3) (Node 16) or [v3-node20](https://github.com/actions/upload-artifact/releases/tag/v3-node20) (Node 20).
-
-The release of upload-artifact@v4 and download-artifact@v4 are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements.
-
-For more information, see the [`@actions/artifact`](https://github.com/actions/toolkit/tree/main/packages/artifact) documentation.
-
-There is also a new sub-action, `actions/upload-artifact/merge`. For more info, check out that action's [README](./merge/README.md).
-
-### Improvements
-
-1. Uploads are significantly faster, upwards of 90% improvement in worst case scenarios.
-2. Once uploaded, an Artifact ID is returned and Artifacts are immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed before an ID was available or any APIs could be utilized.
-3. The contents of an Artifact are uploaded together into an _immutable_ archive. They cannot be altered by subsequent jobs unless the Artifacts are deleted and recreated (where they will have a new ID). Both of these factors help reduce the possibility of accidentally corrupting Artifact files.
-4. The compression level of an Artifact can be manually tweaked for speed or size reduction.
-
-### Breaking Changes
-
-1. On self hosted runners, additional [firewall rules](https://github.com/actions/toolkit/tree/main/packages/artifact#breaking-changes) may be required.
-2. Uploading to the same named Artifact multiple times.
-
-    Due to how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple Artifacts with different names, or only upload once. Otherwise you _will_ encounter an error.
-
-3. Limit of Artifacts for an individual job. Each job in a workflow run now has a limit of 500 artifacts.
-4. With `v4.4` and later, hidden files are excluded by default.
-
-For assistance with breaking changes, see [MIGRATION.md](docs/MIGRATION.md).
+Check out the [releases page](https://github.com/actions/upload-artifact/releases) for details on what's new.
 
 ## Note
 
@@ -96,6 +58,10 @@ We will still provide security updates for this project and fix major breaking c
 
 You are welcome to still raise bugs in this repo.
 
+## GHES Support
+
+`upload-artifact@v4+` is not currently supported on GitHub Enterprise Server (GHES). If you are on GHES, you must use [v3.2.2](https://github.com/actions/upload-artifact/releases/tag/v3.2.2) (Node 24) or [v3.2.2-node20](https://github.com/actions/upload-artifact/releases/tag/v3.2.2-node20) (Node 20).
+
 ## Usage
 
 ### Inputs
@@ -142,6 +108,11 @@ You are welcome to still raise bugs in this repo.
     # enabled this to avoid uploading sensitive information.
     # Optional. Default is 'false'
     include-hidden-files:
+
+    # Whether to zip the artifact files before upload
+    # If 'false', only a single file can be uploaded. The name of the file will be used as the artifact name (the 'name' parameter is ignored)
+    # Optional. Default is 'true'
+    archive:
 ```
 
 ### Outputs
@@ -154,7 +125,7 @@ You are welcome to still raise bugs in this repo.
 
 ## Examples
 
-### Upload an Individual File
+### Upload an Individual File (Zipped)
 
 ```yaml
 steps:
@@ -166,6 +137,18 @@ steps:
     path: path/to/artifact/world.txt
 ```
 
+### Upload an Individual File (Unzipped)
+
+```yaml
+steps:
+- run: mkdir -p path/to/artifact
+- run: echo hello > path/to/artifact/world.txt
+- uses: actions/upload-artifact@v4
+  with:
+    path: path/to/artifact/world.txt
+    archive: false
+```
+
 ### Upload an Entire Directory
 
 ```yaml
@@ -476,15 +459,11 @@ Within an individual job, there is a limit of 500 artifacts that can be created
 
 You may also be limited by Artifacts if you have exceeded your shared storage quota. Storage is calculated every 6-12 hours. See [the documentation](https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions#calculating-minute-and-storage-spending) for more info.
 
-### Zip archives
-
-When an Artifact is uploaded, all the files are assembled into an immutable Zip archive. There is currently no way to download artifacts in a format other than a Zip or to download individual artifact contents.
-
 ### Permission Loss
 
-File permissions are not maintained during artifact upload. All directories will have `755` and all files will have `644`. For example, if you make a file executable using `chmod` and then upload that file, post-download the file is no longer guaranteed to be set as an executable.
+File permissions are not maintained during zipped artifact upload. All directories will have `755` and all files will have `644`. For example, if you make a file executable using `chmod` and then upload that file with `archive: true`, post-download the file is no longer guaranteed to be set as an executable.
 
-If you must preserve permissions, you can `tar` all of your files together before artifact upload. Post download, the `tar` file will maintain file permissions and case sensitivity.
+If you must preserve permissions, you can `tar` all of your files together before artifact upload and upload that file directly with `archive: false`. Post download, the `tar` file will maintain file permissions and case sensitivity.
 
 ```yaml
 - name: 'Tar files'
@@ -493,8 +472,8 @@ If you must preserve permissions, you can `tar` all of your files together befor
 - name: 'Upload Artifact'
   uses: actions/upload-artifact@v4
   with:
-    name: my-artifact
     path: my_files.tar
+    archive: false
 ```
 
 ## Where does the upload go?