GitXplorerGitXplorer
r

stig

public
566 stars
24 forks
48 issues

Commits

List of commits on branch master.
Unverified
dfc1cec26503d1c24f2119149eb6b3fdba8e569e

Bump version

rrndusr committed 8 days ago
Unverified
0e4e2449267b951c1199563cae68b7611c87ea70

Update CHANGELOG

rrndusr committed 8 days ago
Unverified
d5286cb6d7c47c7170549656ccb59d04c44306db

set Timestamp.NEVER to negative value (Fixes #245)

rrsekman committed 9 months ago
Unverified
7d7c90f856f539b876a4e974bf4f3a8f98783ea3

fix: prevent an infinite loop in `interactive` command

rrsekman committed 23 days ago
Unverified
bab6a899f905dc06ea5ebb8507d4e9a9364649f3

Update CHANGELOG

rrndusr committed 5 months ago
Unverified
5c8410431366a60227eda9a88de46334a3b029a2

Bump version

rrndusr committed 5 months ago

README

The README file for this repository.

** Features

  • Filters are used to select torrents for listing, starting/stopping, deleting, etc
  • Tabs allow you to open and switch between multiple lists (torrents, peers, files, etc)
  • Commands do almost everything, and they can be invoked
    • through single- or multi-key (think emacs) keybindings,
    • by entering them in a command prompt in the TUI (think vi) with tab completion,
    • by providing them as CLI arguments when invoking stig (think git),
    • or by listing them in an rc file which is automatically loaded.
  • Color themes support 16 and 256 colors
  • Complete built-in documentation with help command or --help argument
  • Full API abstraction layer makes it possible to add support for other BitTorrent clients with RPC interfaces (contributors are welcome)

** Examples Add two torrents, one by file and one by hash, and exit #+BEGIN_SRC sh $ stig add /path/to/some.torrent d4d6b73851fe3288e40389a8e1fb98124a9b9ba5 #+END_SRC

Connect to non-default host and present the TUI #+BEGIN_SRC sh $ stig set connect.host torrents.local #+END_SRC

Print all uploading and/or downloading torrents on localhost:9092 and exit #+BEGIN_SRC sh $ stig set connect.port 9092 ; ls active #+END_SRC

List torrents with more than 50 seeds, then remove them #+BEGIN_SRC sh $ stig ls 'seeds>50' $ stig rm 'seeds>50' #+END_SRC

Stop down/uploading torrents with /foo/ in their download path and a ratio above 10 #+BEGIN_SRC sh $ stig stop 'path~/foo/&ratio>10' #+END_SRC

Open two tabs with different torrent lists: - slowly uploading torrents with /foo/ in their download path - small or well-seeded torrents, sorted by size (ascending) and number of seeds (descending) #+BEGIN_SRC sh $ stig tab ls 'path~/foo/&rate-up<10k' ; tab ls 'size<500M|seeds>=1k' --sort 'size,!seeds' #+END_SRC

** Configuration and Scripting All configuration is done in an rc file, which is just a script containing a list of commands (think vim and .vimrc) that are executed during startup. The default rc file is $XDG_CONFIG_HOME/stig/rc. XDG_CONFIG_HOME defaults to $HOME/.config if not set. Because a default rc file is empty, it is not created automatically to avoid clutter.

See stig help cfgman for more information.

*** Example rc file #+BEGIN_SRC # Host that runs Transmission daemon set connect.host example.org set connect.port 123

# Update torrent/peer/file/etc lists every 10 seconds
set tui.poll 10

# Default columns in torrent lists
set columns.torrents name ratio rate-up rate-down

# Open a few tabs on startup
tab ls active --sort !%downloaded,path,!rate
tab ls paused --sort !%downloaded --columns name,%downloaded,ratio,size
tab ls isolated --sort tracker --columns name,path
#+END_SRC

Run different rc files either with ~stig -c path/to/file~ or with the ~rc~
command.  You can even turn them into executables with the shebang
~#!/path/to/stig -Tc~ (~-T~ disables the TUI, ~-c~ specifies the rc file).

*** Example maintenance script #+BEGIN_SRC #!/path/to/stig -Tc rm path=/path/to/torrents/trash pause seeds>100 start seeds<20&size>10G|seeds<50&size>20G #+END_SRC

** Installation The [[https://pypi.python.org/pypi/stig][latest release]] is always on PyPI.

*** Packages - Arch (AUR): [[https://aur.archlinux.org/packages/stig][stig]], [[https://aur.archlinux.org/packages/stig-git][stig-git]] - NixOS: [[https://nixos.org/nixos/packages.html?attr=stig&query=stig][stig]] - Alpine Linux: [[https://pkgs.alpinelinux.org/packages?name=stig&branch=edge][stig]]

*** Pipx (recommended) [[https://github.com/pipxproject/pipx][Pipx]] installs applications in self-contained virtual environments in $HOME/.local/pipx/ that include all dependencies. Executables are sym-linked to $HOME/.local/bin/.

#+BEGIN_SRC sh
$ pipx install stig
$ pipx upgrade stig
$ pipx uninstall stig
#+END_SRC

*** Pip [[https://pip.pypa.io/en/stable/][pip]] installs applications with their dependencies in the system-wide (/usr/local) or user-wide ($HOME/.local) environment.

#+BEGIN_SRC sh
$ pip3 install stig         # Installs in /usr/local/
$ pip3 install --user stig  # Installs in $HOME/.local/
#+END_SRC

To update, add the ~--upgrade~ or ~-U~ option.

*** Extras The following extras are available to enable optional features: - setproctitle :: Strip arguments from process title when running in tmux session (this requires Python headers; e.g. apt-get install libpython3-dev) - proxy :: Tunnel the connection to the Transmission daemon through a SOCKS5, SOCKS4 or HTTP proxy

To install stig with dependencies for an extra:
#+BEGIN_SRC sh
$ pipx install 'stig[setproctitle,proxy]'              # For pipx version>=0.15.0.0
$ pipx install stig --spec 'stig[setproctitle,proxy]'  # For pipx version<0.15.0.0
#+END_SRC

*** Development version To install the latest development version of stig with pipx: #+BEGIN_SRC sh $ pipx install 'git+https://github.com/rndusr/stig.git#egg=stig' # For pipx version>=0.15.0.0 $ pipx install stig --spec 'git+https://github.com/rndusr/stig.git#egg=stig' # For pipx version<0.15.0.0 #+END_SRC

*** Developing To make your code changes effective immediately, you can either run python3 -m stig in the project directory or use pip3's --editable option.

**** Run tests with your system's Python version To run the tests with the Python version that is installed on your system, simply run make test in the project directory. This creates a virtual environment in ./venv, installs stig and its dependencies in there and runs all tests.

 If you want to only run tests for a specific module or package:

 1. Create a virtual environment with all dependencies:
    ~make venv~
 2. Activate the virtual environment:
    ~source venv/bin/activate~
 3. Pass any path in the ~tests~ directory to pytest:
    ~pytest tests/settings_test~

**** Run tests with all supported Python versions 1. Install and set up [[https://github.com/pyenv/pyenv#table-of-contents][pyenv]]. 2. With pyenv, install the supported Python versions listed in .setup.py. 3. In stig's project directory, create a virtual environment with all dependencies: make venv 4. Activate the virtual environment: source venv/bin/activate 5. Run the tests for each supported Python version: tox 6. Pass arguments to pytest: tox -- --exitfirst tests/settings_test

** Requirements

** Contributing Pull requests, bug reports, features requests, ideas for improvement and all other constructive contributions are welcome.

If you want to contribute code and get stuck, don't know where to even begin, or just to make sure you're not duplicating someone else's efforts, open an issue.

Please submit your custom themes if you would like them to be included in stig.

** License stig is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [[https://www.gnu.org/licenses/gpl-3.0.txt][GNU General Public License]] for more details.

#+STARTUP: showeverything #+OPTIONS: num:nil #+OPTIONS: ^:{}