From 0126ce6586ee4233eb630d9aef14f0988b682262 Mon Sep 17 00:00:00 2001 From: blu3 Date: Fri, 31 Jan 2025 16:51:57 +0300 Subject: [PATCH] Better readme test --- README.md | 201 +++++++++++++++++++++++++++--------------------------- 1 file changed, 102 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index ea7f9c3d..4c06b7de 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,58 @@ -

-croc -
-Version -Build -Status -

This project is supported by Github sponsors.

+ croc +
+ + Version + + + Build Status + +

+

+ This project is supported by GitHub sponsors. +

+ +## About `croc` is a tool that allows any two computers to simply and securely transfer files and folders. AFAIK, *croc* is the only CLI file-transfer tool that does **all** of the following: -- allows **any two computers** to transfer data (using a relay) -- provides **end-to-end encryption** (using PAKE) -- enables easy **cross-platform** transfers (Windows, Linux, Mac) -- allows **multiple file** transfers -- allows **resuming transfers** that are interrupted -- local server or port-forwarding **not needed** -- **ipv6-first** with ipv4 fallback -- can **use proxy**, like tor +- Allows **any two computers** to transfer data (using a relay) +- Provides **end-to-end encryption** (using PAKE) +- Enables easy **cross-platform** transfers (Windows, Linux, Mac) +- Allows **multiple file** transfers +- Allows **resuming transfers** that are interrupted +- No need for local server or port-forwarding +- **IPv6-first** with IPv4 fallback +- Can **use a proxy**, like Tor -For more information about `croc`, see [my blog post](https://schollz.com/software/croc6) or read a [recent interview I did](https://console.substack.com/p/console-91). +For more information about `croc`, see [my blog post](https://schollz.com/tinker/croc6/) or read a [recent interview I did](https://console.substack.com/p/console-91). ![Example](src/install/customization.gif) ## Install -Download [the latest release for your system](https://github.com/schollz/croc/releases/latest), or install a release from the command-line: +You can download [the latest release for your system](https://github.com/schollz/croc/releases/latest), or install a release from the command-line: -``` +```bash curl https://getcroc.schollz.com | bash ``` +### On macOS -On macOS you can install the latest release with [Homebrew](https://brew.sh/): +Using [Homebrew](https://brew.sh/): + ```bash + brew install croc + ``` -``` -brew install croc -``` +Using [MacPorts](https://www.macports.org/): + ```bash + sudo port selfupdate + sudo port install croc + ``` -On macOS you can also install the latest release with [MacPorts](https://macports.org/): +### On Windows -``` -sudo port selfupdate -sudo port install croc -``` - -On Windows you can install the latest release with [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org), or [Winget](https://learn.microsoft.com/en-us/windows/package-manager/): +You can install the latest release with [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/), or [Winget](https://learn.microsoft.com/windows/package-manager/): ```bash scoop install croc @@ -61,74 +66,92 @@ choco install croc winget install schollz.croc ``` -On Unix you can install the latest release with [Nix](https://nixos.org/nix): +### On Unix + +You can install the latest release with [Nix](https://nixos.org/): ```bash nix-env -i croc ``` +### On Alpine Linux -On Alpine Linux you have to install dependencies first: +First, install dependencies: ```bash apk add bash coreutils wget -qO- https://getcroc.schollz.com | bash ``` -On Arch Linux you can install the latest release with `pacman`: +### On Arch Linux + +Install with `pacman`: ```bash pacman -S croc ``` -On Fedora you can install with `dnf`: +### On Fedora + +Install with `dnf`: ```bash dnf install croc ``` -On Gentoo you can install with `portage`: +### On Gentoo + +Install with `portage`: ```bash emerge net-misc/croc ``` -On Termux you can install with `pkg`: +### On Termux + +Install with `pkg`: ```bash pkg install croc ``` -On FreeBSD you can install with `pkg`: +### On FreeBSD + +Install with `pkg`: ```bash pkg install croc ``` -On Linux, macOS, and Windows you can install from [conda-forge](https://github.com/conda-forge/croc-feedstock/) globally with [`pixi`](https://pixi.sh/): +### On Linux, macOS, and Windows via Conda + +You can install from [conda-forge](https://github.com/conda-forge/croc-feedstock) globally with [`pixi`](https://pixi.sh/): ```bash pixi global install croc ``` -or into a particular environment with [`conda`](https://docs.conda.io/projects/conda/): +Or install into a particular environment with [`conda`](https://docs.conda.io/projects/conda/): ```bash conda install --channel conda-forge croc ``` -Or, you can [install Go](https://golang.org/dl/) and build from source (requires Go 1.17+): +### Build from Source + +If you prefer, you can [install Go](https://go.dev/dl/) and build from source (requires Go 1.17+): ```bash go install github.com/schollz/croc/v10@latest ``` -On Android there is a 3rd party F-Droid app [available to download](https://f-droid.org/en/packages/com.github.howeyc.crocgui/). +### On Android +There is a 3rd-party F-Droid app [available to download](https://f-droid.org/packages/com.github.howeyc.crocgui/). ## Usage -To send a file, simply do: +To send a file, simply do: ```bash $ croc send [file(s)-or-folder] @@ -136,62 +159,55 @@ Sending 'file-or-folder' (X MB) Code is: code-phrase ``` -Then to receive the file (or folder) on another computer, you can just do +Then, to receive the file (or folder) on another computer, run: -``` +```bash croc code-phrase ``` The code phrase is used to establish password-authenticated key agreement ([PAKE](https://en.wikipedia.org/wiki/Password-authenticated_key_agreement)) which generates a secret key for the sender and recipient to use for end-to-end encryption. -There are a number of configurable options (see `--help`). A set of options (like custom relay, ports, and code phrase) can be set using `--remember`. +### Customizations & Options -### Using `croc` on Linux or Mac OS +#### Using `croc` on Linux or macOS -On Linux and Mac OS, the sending & receiving is slightly different to avoid [leaking the secret via the process name](https://nvd.nist.gov/vuln/detail/CVE-2023-43621). On these systems you will need to run `croc` with the secret as an environment variable. For example, to receive with the secret `***`: +On Linux and macOS, the sending and receiving process is slightly different to avoid [leaking the secret via the process name](https://nvd.nist.gov/vuln/detail/CVE-2023-43621). You will need to run `croc` with the secret as an environment variable. For example, to receive with the secret `***`: ```bash CROC_SECRET=*** croc ``` -This will show only `croc` in the process list of a multi-user system and not leak the secret. - -For a single-user system the default behavior can be permanently enabled by running +For single-user systems, the default behavior can be permanently enabled by running: ```bash croc --classic ``` -and confirming. -Run this command again to disable classic mode. +#### Custom Code Phrase -### Custom code phrase - -You can send with your own code phrase (must be more than 6 characters). +You can send with your own code phrase (must be more than 6 characters): ```bash croc send --code [code-phrase] [file(s)-or-folder] ``` -### Allow overwriting without prompt +#### Allow Overwriting Without Prompt -By default, croc will prompt whether to overwrite a file. You can automatically overwrite files by using the `--overwrite` flag (recipient only). For example, receive a file to automatically overwrite: +To automatically overwrite files without prompting, use the `--overwrite` flag: ```bash croc --yes --overwrite ``` -### Excluding folders +#### Excluding Folders -You can exclude folders from being sent by using the `--exclude` flag with a string of comma-delimited exclusions. For example, if you want to send a folder but exclude any `node_modules` folders or `.venv` folders: +To exclude folders from being sent, use the `--exclude` flag with comma-delimited exclusions: ```bash croc send --exclude "node_modules,.venv" [folder] ``` -Exclusions work by excluding any absolute path that contains the string. So in the above example, any folder named `node_modules` or `.venv` will be excluded from the transfer. - -### Use pipes - stdin and stdout +#### Use Pipes - stdin and stdout You can pipe to `croc`: @@ -199,93 +215,80 @@ You can pipe to `croc`: cat [filename] | croc send ``` -In this case `croc` will automatically use the stdin data and send and assign a filename like "croc-stdin-123456789". To receive to `stdout` at you can always just use the `--yes` will automatically approve the transfer and pipe it out to `stdout`. +To receive the file to `stdout`, you can use: ```bash croc --yes [code-phrase] > out ``` -All of the other text printed to the console is going to `stderr` so it will not interfere with the message going to `stdout`. +#### Send Text - -### Send text - -Sometimes you want to send URLs or short text. In addition to piping, you can easily send text with `croc`: +To send URLs or short text, use: ```bash croc send --text "hello world" ``` -This will automatically tell the receiver to use `stdout` when they receive the text so it will be displayed. +#### Use a Proxy - -### Use a proxy - -You can use a proxy as your connection to the relay by adding a proxy address with `--socks5`. For example, you can send via a tor relay: +You can send files via a proxy by adding `--socks5`: ```bash croc --socks5 "127.0.0.1:9050" send SOMEFILE ``` -### Change encryption curve +#### Change Encryption Curve -You can choose from several different elliptic curves to use for encryption by using the `--curve` flag. Only the recipient can choose the curve. For example, receive a file using the P-521 curve: +To choose a different elliptic curve for encryption, use the `--curve` flag: ```bash croc --curve p521 ``` -Available curves are P-256, P-348, P-521 and SIEC. P-256 is the default curve. +#### Change Hash Algorithm -### Change hash algorithm - -You can choose from several different hash algorithms. The default is the `xxhash` algorithm which is fast and thorough. If you want to optimize for speed you can use the `imohash` algorithm which is even faster, but since it samples files (versus reading the whole file) it can mistakenly determine that a file is the same on the two computers transferring - though this is only a problem if you are syncing files versus sending a new file to a computer. +For faster hashing, use the `imohash` algorithm: ```bash croc send --hash imohash SOMEFILE ``` -### Self-host relay +#### Self-host Relay -The relay is needed to staple the parallel incoming and outgoing connections. By default, `croc` uses a public relay but you can also run your own relay: +You can run your own relay: ```bash croc relay ``` -By default it uses TCP ports 9009-9013. Make sure to open those up. You can customize the ports (e.g. `croc relay --ports 1111,1112`), but you must have a minimum of **2** ports for the relay. The first port is for communication and the subsequent ports are used for the multiplexed data transfer. +By default, it uses TCP ports 9009-9013. You can customize the ports (e.g., `croc relay --ports 1111,1112`), but at least **2** ports are required. -You can send files using your relay by entering `--relay` to change the relay that you are using if you want to custom host your own. +To send files using your relay: ```bash croc --relay "myrelay.example.com:9009" send [filename] ``` -Note, when sending, you only need to include the first port (the communication port). The subsequent ports for data transfer will be transmitted back to the user from the relay. - -#### Self-host relay (docker) - -If it's easier you can also run a relay with Docker: +#### Self-host Relay with Docker +You can also run a relay with Docker: ```bash docker run -d -p 9009-9013:9009-9013 -e CROC_PASS='YOURPASSWORD' schollz/croc ``` -Be sure to include the password for the relay otherwise any requests will be rejected. +To send files using your custom relay: ```bash croc --pass YOURPASSWORD --relay "myreal.example.com:9009" send [filename] ``` -Note: when including `--pass YOURPASSWORD` you can instead pass a file with the password, e.g. `--pass FILEWITHPASSWORD`. - -## License - -MIT - ## Acknowledgements -`croc` has gone through many iterations, and I am awed by all the great contributions! If you feel like contributing, in any way, by all means you can send an Issue, a PR, or ask a question. +`croc` has evolved through many iterations, and I am thankful for the contributions! Special thanks to: -Thanks [@warner](https://github.com/warner) for the [idea](https://github.com/warner/magic-wormhole), [@tscholl2](https://github.com/tscholl2) for the [encryption gists](https://gist.github.com/tscholl2/dc7dc15dc132ea70a98e8542fefffa28), [@skorokithakis](https://github.com/skorokithakis) for [code on proxying two connections](https://www.stavros.io/posts/proxying-two-connections-go/). Finally thanks for making pull requests [@maximbaz](https://github.com/maximbaz), [@meyermarcel](https://github.com/meyermarcel), [@Girbons](https://github.com/Girbons), [@techtide](https://github.com/techtide), [@heymatthew](https://github.com/heymatthew), [@Lunsford94](https://github.com/Lunsford94), [@lummie](https://github.com/lummie), [@jesuiscamille](https://github.com/jesuiscamille), [@threefjord](https://github.com/threefjord), [@marcossegovia](https://github.com/marcossegovia), [@csleong98](https://github.com/csleong98), [@afotescu](https://github.com/afotescu), [@callmefever](https://github.com/callmefever), [@El-JojA](https://github.com/El-JojA), [@anatolyyyyyy](https://github.com/anatolyyyyyy), [@goggle](https://github.com/goggle), [@smileboywtu](https://github.com/smileboywtu), [@nicolashardy](https://github.com/nicolashardy), [@fbartels](https://github.com/fbartels), [@rkuprov](https://github.com/rkuprov), [@hreese](https://github.com/hreese), [@xenrox](https://github.com/xenrox) and [Ipar](https://github.com/lpar)! +- [@warner](https://github.com/warner) for the [idea](https://github.com/magic-wormhole/magic-wormhole) +- [@tscholl2](https://github.com/tscholl2) for the [encryption gists](https://gist.github.com/tscholl2/dc7dc15dc132ea70a98e8542fefffa28) +- [@skorokithakis](https://github.com/skorokithakis) for [proxying two connections](https://www.stavros.io/posts/proxying-two-connections-go/) + +And many more!