From d95038a6500686264aab95a0d338b2f15671db60 Mon Sep 17 00:00:00 2001 From: Gnarwhal Date: Sun, 8 Sep 2024 22:47:30 +0000 Subject: [PATCH] Updated README.md --- README.md | 127 +++++++----------------------------------------------- examples | 2 +- 2 files changed, 16 insertions(+), 113 deletions(-) diff --git a/README.md b/README.md index e5e6760..38b03cc 100644 --- a/README.md +++ b/README.md @@ -4,123 +4,26 @@ Upload files to a server via ssh ## Documentation -### Arguments +- **End User**: coming soon... +- **Plugin Developer**: coming soon... -#### `-h` `--help` -Show the help message and exit +## Installing -#### `-v` `--version` -Show the program's version number and exit - -#### `-l` `--latest` -Upload the most recently modified file in `source_directory` - -#### `-p` `--paste` -Upload the contents of the clipboard as a `.txt` file - -#### `-f FILE` `--file FILE` -Upload a file - -#### `-c` `--copy` -Copy the resultant URL to the clipboard - -### Configuration File - -The configuration file is located at `$XDG_CONFIG_DIR/sshare/config.toml`. -If `XDG_CONFIG_DIR` is not set, then it will read from `$HOME/.config/sshare/config.toml` instead. - -#### `source_directory` -The directory from which `--latest` reads. -- [x] Optional - Cannot use `--latest` if it is not set - -#### `host` +SSHare is not available on [PyPI](https://pypi.org). +To install it you will need to clone the repo and use pip to install it ``` -https://example.com:4430/path/to/files/* -^---^ ^---------^ ^--^^------------^ - | | | | - | | | +- `host.path` = "/path/to/files" - | | +----- `host.port` = 4430 - | +----------------- `host.name` = "example.com" - +------------------------- `host.protocol` = "https" - -https://example.com/* - ^---------^ - | - | `host.path` Not set - | `host.port` Not set - +----------------- `host.name` = "example.com" - `host.protocol` Not set (Defaults to `https`) -``` -#### `host.protocol` -The protocol by which the file is served -- [x] Optional - Default: `https` - -#### `host.name` -The name of the host (e.g. `example.com`, `1.1.1.1`) -- [ ] Not optional - -#### `host.port` -The port from which the host is serving files -- [x] Optional - Default: `None` (which means the default port for the protocol) - -#### `host.path` -The subpath from which the host is serving files. If set, `host.path` must start -with and **NOT** end with a `/` (e.g. `/path/to/files` not `path/to/files/`) -- [x] Optional - If the host is serving from the root - -#### `ssh` -``` -ssh -p 1234 example@example.com:/srv/static - ^--^ ^-----^ ^---------^ ^---------^ - | | | | - | | | +- `ssh.path` = "/srv/static" - | | +------------- Uses `host.name` - | +--------------------- `ssh.user` = "example" - +-------------------------- `ssh.port` = 1234" - -ssh example@example.com:/srv/static - ^-----^ ^---------^ ^---------^ - | | | - | | +- `ssh.path` = "/srv/static" - | +------------- Uses `host.name` - +--------------------- `ssh.user` Doesn't need to be set if `example` is - the name of the user running `sshare` - `ssh.part` Not set (Defaults to 22) +git clone https://forge.monodon.me/Gnarwhal/sshare.git +cd sshare +pip install ./ ``` -#### `ssh.port` -The port the server is listening for ssh connections on -- [x] Optional - Default: 22 +By default, the only dependency SSHare has is the system's `ssh` (and `scp`) commands. +Beyond that it only utilises the python standard library. -#### `ssh.user` -The user to connect to the host with -- [x] Optional - Default: The user that ran `sshare` +### Additional Functionality -#### `ssh.path` -The directory on the host from which static files are being hosted. If set, -`ssh.path` must **NOT** end with a path (e.g. `/srv/static` not `/srv/static/`) -- [ ] Not optional +The base install is fairly bare bones in terms of functionality. +Included in the [`examples/`](https://forge.monodon.me/Gnarwhal/sshare_plugins) submodule, there are included some +plugins which provide some additional conveniences -#### Example Configuration File - -```toml -# config.toml - -source_directory = "/home/example/Pictures/Screenshots" - -# Host is serving static files at https://example.com:443/sshare/* -# Note: both protocol and port would be optional here as https is -# the default protocol and port 443 is the default https port -[host] -protocol = "https" -name = "example.com" -port = 443 -path = "/sshare" - -# Host is listening for ssh connections on port 1234 and -# serving files from the `/srv/sshare` directory -[ssh] -port = 1234 -user = "exampleuser2" -path = "/srv/sshare" -``` +Refer to \[coming soon...\] for information on installing plugins diff --git a/examples b/examples index 92bb65a..8ba852a 160000 --- a/examples +++ b/examples @@ -1 +1 @@ -Subproject commit 92bb65a049942b127ee6108bff5812c110acfe12 +Subproject commit 8ba852a8495b79361b4cc29dec12b6b2137f6bff