mirror of
https://github.com/nukesor/pueue
synced 2024-10-14 19:53:31 +00:00
Fix markdown issues
This commit is contained in:
Arne Beer
parent
25916d3a56
commit
29fe04ad98
66
README.md
66
README.md
|
|
@ -9,7 +9,6 @@
|
|||
[](https://www.paypal.me/arnebeer/)
|
||||
<!---[](https://deps.rs/repo/github/nukesor/pueue) --->
|
||||
|
||||
|
||||
|
||||
|
||||
Pueue is a command-line task management tool for sequential and parallel execution of long-running tasks.
|
||||
|
|
@ -17,11 +16,11 @@ Pueue is a command-line task management tool for sequential and parallel executi
|
|||
Simply put, it's a tool that processes a queue of shell commands.
|
||||
On top of that, there are a lot of convenience features and abstractions.
|
||||
|
||||
|
||||
Since Pueue is not bound to any terminal, you can control your tasks from any terminal on the same machine.
|
||||
The queue will be continuously processed, even if you no longer have any active ssh session.
|
||||
|
||||
It provides functionality for:
|
||||
|
||||
- Scheduling commands that will be executed in their respective working directories
|
||||
- Easy output inspection.
|
||||
- Interaction with running processes
|
||||
|
|
@ -33,11 +32,11 @@ It provides functionality for:
|
|||
- Works on Linux, MacOS and partially on Windows.
|
||||
|
||||
**Disclaimer:** Windows isn't fully supported yet. This means:
|
||||
|
||||
- Pausing/resuming commands doesn't work for now.
|
||||
- Pueue only supports `powershell` for executing commands, keep this in mind when writing commands.
|
||||
|
||||
|
||||
## Why should I use it?
|
||||
## Why should I use it
|
||||
|
||||
Imagine having to unpack or move large amounts of data to various directories.
|
||||
Usually something like this ends with about 10 open terminals/tmux sessions and an over-challenged hard drive.
|
||||
|
|
@ -51,10 +50,10 @@ You can schedule your task and continue on the same shell without waiting.
|
|||
You can specify how many tasks should run in parallel and even group tasks to maximize system resource utilization.
|
||||
You could log off your server and come back later to check on your tasks' progress.
|
||||
|
||||
Heck, you can even set up desktop notifications to get notified or execute parameterized commands as soon as a tasks finishes.
|
||||
|
||||
Heck, you can even set up desktop notifications to get notified or execute parameterized commands as soon as a tasks finishes.
|
||||
|
||||
**A few possible applications:**
|
||||
|
||||
- Copying huge amounts of stuff
|
||||
- Compression tasks
|
||||
- Movie encoding
|
||||
|
|
@ -68,7 +67,7 @@ If you feel like something is missing, please create an issue :).
|
|||
|
||||
PRs are of course very welcome!
|
||||
|
||||
## Installation:
|
||||
## Installation
|
||||
|
||||
There are three different ways to install Pueue.
|
||||
|
||||
|
|
@ -83,43 +82,53 @@ Pueue has been packaged for:
|
|||
|
||||
**Via Cargo**
|
||||
You'll need Rust version `>=1.39`
|
||||
```
|
||||
|
||||
```bash
|
||||
cargo install pueue
|
||||
```
|
||||
|
||||
This will install pueue to `~/.cargo/bin/pueue`
|
||||
|
||||
**From Source**
|
||||
You'll need Rust version `>=1.39`
|
||||
```
|
||||
|
||||
```bash
|
||||
git clone git@github.com:Nukesor/pueue
|
||||
cd pueue
|
||||
cargo install --path .
|
||||
```
|
||||
|
||||
This will install pueue to `~/.cargo/bin/pueue`
|
||||
|
||||
## Starting the Daemon
|
||||
|
||||
### Local
|
||||
|
||||
Just run `pueued` anywhere on your commandline. It'll exit if you close the terminal, though.
|
||||
|
||||
### Background
|
||||
|
||||
To fork `pueued` into the background, add the `-d` or `--daemonize` flag. E.g. `pueued -d`. \
|
||||
The daemon can be then shut down using the client: `pueue shutdown`
|
||||
|
||||
### Systemd
|
||||
|
||||
If you use Systemd and don't install Pueue with a package manager, place `pueued.service` in `/etc/systemd/user/`.
|
||||
Afterward, every user can start/enable their own session with:
|
||||
|
||||
systemctl --user start pueued.service
|
||||
systemctl --user enable pueued.service
|
||||
```bash
|
||||
systemctl --user start pueued.service
|
||||
systemctl --user enable pueued.service
|
||||
```
|
||||
|
||||
|
||||
## How to use it:
|
||||
## How to use it
|
||||
|
||||
**Adding Commands:**
|
||||
|
||||
To add a command just write: `pueue add sleep 60`\
|
||||
If you want to add flags to the command, you can either:
|
||||
|
||||
- add `--` => `pueue add -- ls -al`
|
||||
- surround the command with a string `pueue add 'ls -al'`
|
||||
|
||||
|
|
@ -140,13 +149,13 @@ To look at the current output of a command use `pueue log` or `pueue log $task_i
|
|||
If you want to follow the output of a running command use `git follow $task_id`.
|
||||
To follow stderr, use the `-e` flag.
|
||||
|
||||
|
||||
**Pitfalls:**
|
||||
|
||||
To avoid common pitfalls, please read the [FAQ Section](https://github.com/Nukesor/pueue/blob/master/FAQ.md).
|
||||
|
||||
There is a help option (-h) for all commands.
|
||||
```
|
||||
|
||||
```text
|
||||
Pueue client 0.5.0
|
||||
Arne Beer <contact@arne.beer>
|
||||
Interact with the Pueue daemon
|
||||
|
|
@ -200,7 +209,7 @@ SUBCOMMANDS:
|
|||
The configuration file of Pueue is located in `~/.config/pueue.yml`.
|
||||
The default will be generated after starting pueue once.
|
||||
|
||||
```
|
||||
```yaml
|
||||
---
|
||||
client:
|
||||
daemon_port: "6924"
|
||||
|
|
@ -217,12 +226,15 @@ daemon:
|
|||
groups:
|
||||
cpu: 1
|
||||
```
|
||||
**Client**:
|
||||
|
||||
**Client**:
|
||||
|
||||
- `daemon_port` The port the client tries to connect to.
|
||||
- `secret` The secret, that's used for authentication
|
||||
- `read_local_logs` If the client runs as the same user (and on the same machine) as the daemon, logs don't have to be sent via the socket but rather read directly.
|
||||
|
||||
**Daemon**:
|
||||
**Daemon**:
|
||||
|
||||
- `pueue_directory` The location Pueue uses for its intermediate files and logs.
|
||||
- `default_parallel_tasks` Determines how many tasks should be processed concurrently.
|
||||
- `pause_on_failure` If set to `true`, the daemon stops starting new task as soon as a single task fails. Already running tasks will continue.
|
||||
|
|
@ -231,8 +243,7 @@ daemon:
|
|||
- `callback` The command that will be called after a task finishes. Can be parameterized
|
||||
- `groups` This is a list of the groups with their amount of allowed parallel tasks. It's advised to not manipulate this manually, but rather use the `group` subcommand to create and remove groups.
|
||||
|
||||
|
||||
## Logs
|
||||
## Logs
|
||||
|
||||
All logs can be found in `${pueue_directory}/logs`.
|
||||
Logs of previous Pueue sessions will be created whenever you issue a `reset` or `clean`.
|
||||
|
|
@ -255,13 +266,12 @@ As a result, there'll always be a single task that copies stuff, while two tasks
|
|||
This removes the problem of scheduling tasks in a way that the system might get slow.
|
||||
At the same time, you're able to maximize resource utilization.
|
||||
|
||||
|
||||
### Aliases
|
||||
|
||||
To get basic aliasing, simply put a `pueue_aliases.yml` besides your `pueue.yml`.
|
||||
Its contents should look something like this:
|
||||
|
||||
```
|
||||
```yaml
|
||||
ls: "ls -ahl"
|
||||
rsync: "rsync --recursive --partial --perms --progress"
|
||||
```
|
||||
|
|
@ -271,13 +281,13 @@ This means, that for instance `ls ~/ && ls /` will result in `ls -al ~/ && ls /`
|
|||
|
||||
If you want something like this, it's probably best to either create a task for each command or to write a custom script.
|
||||
|
||||
|
||||
### Callbacks
|
||||
### Callbacks
|
||||
|
||||
You can specify a callback that will be called every time a task finishes.
|
||||
The callback can be parameterized with some variables.
|
||||
|
||||
These are the available variables that can be used to create a command:
|
||||
|
||||
- `{{ id }}`
|
||||
- `{{ command }}`
|
||||
- `{{ path }}`
|
||||
|
|
@ -285,11 +295,13 @@ These are the available variables that can be used to create a command:
|
|||
- `{{ group }}`
|
||||
|
||||
Example callback:
|
||||
```
|
||||
|
||||
```yaml
|
||||
callback: "notify-send \"Task {{ id }}\nCommand: {{ command }}\nPath: {{ path }}\nFinished with status '{{ result }}'\""
|
||||
```
|
||||
|
||||
### Shell completion files
|
||||
|
||||
Shell completion files can be created on the fly with `pueue completions $shell $directory`.
|
||||
There's also a `build_completions.sh` script, which creates all completion files in the `utiles/completions` directory.
|
||||
|
||||
|
|
@ -301,11 +313,10 @@ This can be used to easily incorporate it into window manager bars, such as i3ba
|
|||
## Scripting
|
||||
|
||||
When calling pueue commands in a script, you might need to sleep for a short amount of time for now.
|
||||
The pueue server processes requests asynchronously, whilst the TaskManager runs it's own update loop with a small sleep.
|
||||
The pueue server processes requests asynchronously, whilst the TaskManager runs it's own update loop with a small sleep.
|
||||
(The TaskManager handles everything related to starting, stopping and communicating with processes.)
|
||||
|
||||
A sleep in scripts will probably become irrelevant, as soon as this bug in rust-lang is fixed: https://github.com/rust-lang/rust/issues/39364
|
||||
|
||||
A sleep in scripts will probably become irrelevant, as soon as this bug in rust-lang is fixed: [issue](https://github.com/rust-lang/rust/issues/39364)
|
||||
|
||||
# Contributing
|
||||
|
||||
|
|
@ -316,5 +327,4 @@ It's always nice to know what you're working on and I might have a few suggestio
|
|||
|
||||
There's also the [Contribution Guide](https://github.com/Nukesor/pueue/blob/master/CHANGELOG.md), which is supposed to give you a brief overview and introduction into the project.
|
||||
|
||||
|
||||
Copyright © 2019 Arne Beer ([@Nukesor](https://github.com/Nukesor))
|
||||
|
|
|
|||
Loading…
Reference in a new issue