docs: Improve README with better structure and documentation

README.md

@@ -1,70 +1,161 @@
-# GOMAJOR
+# gomajor
 
-> A tool for major version upgrades
+[![Go Reference](https://pkg.go.dev/badge/github.com/icholy/gomajor.svg)](https://pkg.go.dev/github.com/icholy/gomajor)
+[![Go Report Card](https://goreportcard.com/badge/github.com/icholy/gomajor)](https://goreportcard.com/report/github.com/icholy/gomajor)
+
+A tool for major version upgrades of Go modules.
+
+## Overview
+
+`gomajor` helps you manage major version upgrades in your Go projects. It automates the process of upgrading dependencies to new major versions by rewriting import paths and updating your `go.mod` file.
 
 ## Installation
 
 ```sh
 go install github.com/icholy/gomajor@latest
 ```
 
-## Commands
+## Quick Start
 
-* `get` - Upgrade to a major version
-* `list` - List available updates
-* `path` - Modify the module path
+```sh
+# List available major version updates
+gomajor list
 
-Usage format is as follows: `gomajor <command> [arguments]`
+# Upgrade a specific module to its latest major version
+gomajor get github.com/go-redis/redis@latest
 
-## Usage
+# Upgrade all modules to their latest major versions
+gomajor get all
+```
 
-#### List Updates
+## Commands
 
-```
-gomajor list
-```
+### `gomajor list`
 
-#### Update a module to its latest version
+List available major version updates for your dependencies.
 
-```
-gomajor get github.com/go-redis/redis@latest
+**Example:**
+```sh
+$ gomajor list
+github.com/go-redis/redis/v8 [v6.15.9] [v8.11.5]
+github.com/example/foo/v3 [v2.1.0] [v3.0.0]
 ```
 
-#### Switch a module to a specific version
+### `gomajor get <module>[@version]`
 
+Upgrade a module to a new major version. This command:
+- Rewrites import paths in your code to use the new major version
+- Updates `go.mod` with the new version
+- Runs `go mod tidy` to clean up
+
+**Examples:**
+
+Update to the latest major version:
+```sh
+gomajor get github.com/go-redis/redis@latest
 ```
+
+Update to a specific major version:
+```sh
 gomajor get github.com/go-redis/redis@v7
 ```
 
-#### Update all mobules to their latest version
-
-```
+Update all modules to their latest major versions:
+```sh
 gomajor get all
 ```
 
-#### Increment module path version
+**Flags:**
+- `-cached` - Only use cached content from the module proxy (default: `true`)
+- `-rewrite` - Rewrite import paths for all major versions of the module (default: `true`)
 
-```
+### `gomajor path [options]`
+
+Modify the module path in your `go.mod` file. Useful when publishing a new major version of your own module.
+
+**Examples:**
+
+Increment to the next major version:
+```sh
 gomajor path -next
 ```
 
-#### Change module path version
+Change to a specific major version:
+```sh
+gomajor path -version v3
+```
 
+Change the module path entirely:
+```sh
+gomajor path goredis.io
 ```
-gomajor path -version v3
+
+## How It Works
+
+When you upgrade to a new major version, `gomajor`:
+
+1. **Analyzes** your code to find all imports of the specified module
+2. **Rewrites** import paths to use the new major version suffix (e.g., `/v8`)
+3. **Updates** your `go.mod` file with the new version
+4. **Tidies** your module dependencies
+
+### Example
+
+Before:
+```go
+import "github.com/go-redis/redis/v6"
+```
+
+After running `gomajor get github.com/go-redis/redis@v8`:
+```go
+import "github.com/go-redis/redis/v8"
 ```
 
-#### Change module path
+## Important Considerations
+
+### Limitations
+
+- **`replace` directives**: This tool does not understand `replace` directives in `go.mod`
+- **Nested modules**: Nested module structures are not supported
+- **Private modules**: Modules matching `GOPRIVATE` are skipped
+- **Version gaps**: The latest version will not be found if there are gaps between major version numbers (e.g., v1, v3, v5 with no v2 or v4)
+- **Package names**: The `path` command rewrites the module path but does not rewrite package names in your code
+
+### Rewriting Behavior
+
+By default, when you upgrade a module, `gomajor` will rewrite **ALL** import paths for that module, even if you have multiple major versions imported. Use the `-rewrite=false` flag to disable this behavior if needed.
+
+### Module Proxy Caching
 
+By default, `gomajor` only fetches cached content from the module proxy to avoid unnecessary network requests. Use the `-cached=false` flag if you need to fetch the latest information.
+
+## Common Use Cases
+
+### Upgrading All Dependencies
+
+To upgrade all your dependencies to their latest major versions:
+
+```sh
+gomajor get all
 ```
-gomajor path goredis.io
+
+### Publishing a New Major Version
+
+When releasing a new major version of your module:
+
+```sh
+# Increment the major version in go.mod
+gomajor path -next
+
+# Update your code and publish
+git tag v2.0.0
+git push origin v2.0.0
 ```
 
-### Warning:
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+## License
 
-* This tool does not understand `replace` directives or nested modules.
-* By default, only cached content will be fetched from the module proxy (See `-cached` flag).
-* If you have multiple major versions imported, **ALL** of them will be rewritten (See `-rewrite` flag).
-* The latest version will not be found if there are **gaps** between major version numbers.
-* The `path` command does not rewrite package names.
-* Modules matching `GOPRIVATE` are skipped.
+See [LICENSE](LICENSE) file for details.