The-way - A code snippets manager for your terminal.

Overview

Crates.io Build Status GitHub release dependency status GitHub license

The Way

A code snippets manager for your terminal.

Record and retrieve snippets you use every day, or once in a blue moon, without having to spin up a browser. Just call the-way new to add a snippet with a description, a language, and some tags attached.

the-way search fuzzy searches your snippets library (with optional filters on language and tags) and lets you

  • edit a snippet with Shift-Right
  • delete a snippet with Shift-Left
  • copy a particular snippet to your clipboard (with Enter), so you can paste it into whatever editor or IDE you're working with.

See it in action with some self-referential examples (click to open in asciinema):

demo

Table of Contents

Install

Requirements

xclip on Linux and pbcopy on OSX

Binaries

See the releases

  • OSX - allow the-way via System Preferences (necessary in Catalina at least)
  • Linux - chmod +x the-way
  • Currently doesn't work on Windows (waiting on this issue)

With brew

brew tap out-of-cheese-error/the-way && brew install the-way

With cargo

cargo install the-way

With yay

yay -S the-way-git

On Android

Needs Termux, Termux:API and pkg install termux-api

Clone the repository, run cargo build --release, and use target/release/the-way

Upgrading

Some upgrades need a database migration (mentioned in the release notes):

  • Before upgrade
the-way export > snippets.json
the-way clear
  • After upgrade
the-way import snippets.json

Usage

Record, retrieve, search, and categorize code snippets

USAGE:
    the-way <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    new         Add a new code snippet
    cmd         Add a new shell snippet
    search      Fuzzy search to find a snippet and copy, edit or delete it
    sync        Sync snippets to a Gist
    list        Lists (optionally filtered) snippets
    import      Imports code snippets from JSON
    export      Saves (optionally filtered) snippets to JSON
    clear       Clears all data
    complete    Generate shell completions
    themes      Manage syntax highlighting themes
    config      Manage the-way data locations
    edit        Change snippet
    del         Delete snippet
    cp          Copy snippet to clipboard
    view        View snippet
    help        Prints this message or the help of the given subcommand(s)

Features

Main features

  • Add code and shell snippets
  • Interactive fuzzy search with edit, delete and copy to clipboard functionality
  • Filter by tag, date, language and/or regex pattern
  • Import / export via JSON
  • Import from Gist (with the-way import -g <gist_url>)
  • Sync to gist
  • Syntax highlighting

Shell commands

the-way cmd (inspired by pet) makes it easier to save single-line bash/shell snippets with variables that can be filled in whenever the snippet is needed.

Add the following function according to your shell of choice. Every time you spend ages hand-crafting the perfect command: run it, close all the stackoverflow tabs, and run cmdsave to save it to the-way. You can then use cmdsearch to search these shell snippets and have the selected one already pasted into the terminal, ready to run.

bash

function cmdsave() {
  PREV=$(echo `history | tail -n2 | head -n1` | sed 's/[0-9]* //')
  sh -c "the-way cmd `printf %q "$PREV"`"
}

function cmdsearch() {
  BUFFER=$(the-way search --stdout --languages="sh")
  bind '"\e[0n": "'"$BUFFER"'"'; printf '\e[5n'
}

zsh

function cmdsave() {
  PREV=$(fc -lrn | head -n 1)
  sh -c "the-way cmd `printf %q "$PREV"`"
}

function cmdsearch() {
  BUFFER=$(the-way search --stdout --languages="sh")
  print -z $BUFFER
}

fish

function cmdsave
  set line (echo $history[1])
  the-way cmd $line
end

function cmdsearch
  commandline (the-way search --languages=sh --stdout)
end

You'll usually want different parameters each time you need a shell command: save variables in a shell snippet as <param> or <param=default_value> and every time you select it you can interactively fill them in (or keep the defaults). Parameters can appear more than once, just use the same name and write in the default the first time it's used.

Here's another self-referential example that saves a shell command to add new language syntaxes:

cmd_demo

(todo: Use cmdsearch instead of search)

Sync to Gist

the-way sync syncs snippets to a Gist, each named snippet_<index>.<extension>, with an index.md file linking each snippet's description. Local updates and deletions are uploaded to the Gist and Gist updates are downloaded.

gist

This functionality needs a GitHub access token with the "gist" scope. Either enter this token on running sync for the first time or set it to the environment variable $THE_WAY_GITHUB_TOKEN.

Shell completions

the-way complete zsh > .oh-my-zsh/completions/_the-way
exec zsh

Syntax highlighting

The Way maps languages to their extensions and uses this to

  1. Enable syntax highlighting in $EDITOR (if the editor supports it),
  2. Upload snippets to Gist with the correct extension,
  3. Add a small colored language indicator (GitHub-flavored)
  4. Syntax highlight code in the terminal

The last point can be customized via the-way themes.

Use the-way themes set to see available themes and enable a theme.

Default themes:

Darcula
InspiredGitHub
Solarized (dark)
Solarized (light)
base16-eighties.dark
base16-mocha.dark
base16-ocean.dark
base16-ocean.light
base16-tomorrow.dark
base16-twilight.dark

Use the-way themes add <theme.tmTheme> to add a new theme to your themes folder. Theme files need to be in Sublime's .tmTheme format. Searching GitHub for .tmTheme pulls up some examples.

Use the-way themes language <language.sublime-syntax> to add highlight support for a new language (many languages are supported by default). Syntax files need to be in Sublime's sublime-syntax format. Zola has a nice collection of such files.

Here's how it looks before and after adding Kotlin.sublime-syntax:

  • Before:

kotlin_plain

  • After:

kotlin_highlight

To get syntax highlighting for code blocks in markdown files, download and add the patched Markdown.sublime-syntax file in this repository, taken from bat (the default syntax file doesn't do this anymore)

Configuration

The default config TOML file is located in

  • Linux: /home/<username>/.config/the-way
  • Mac: /Users/<username>/Library/Preferences/rs.the-way

This file contains locations of data directories, which are automatically created and set according to XDG and Standard Directories guidelines. Change this by creating a config file with the-way config default > config.toml and then setting the environment variable $THE_WAY_CONFIG to point to this file.

Why "The Way"?

The name is a reference to the Way of Mrs.Cosmopilite, kōans for every situation.

Comments
  • Replace copy_to_clipboard code with arboard

    Replace copy_to_clipboard code with arboard

    arboard seems to do the right thing when it comes to X11 clipboard handling. Should allow replacing the current very ugly xclip/pbcopy hack in utils.rs. Also, replacing clipboard with arboard in tests/cli.rs should allow copy tests to run on Linux CI as well, which is ideal.

    good first issue 
    opened by Ninjani 12
  • Editing a snippet in an editor

    Editing a snippet in an editor

    When editing an existing snippet (the-way search -> select -> shift+right), after confirming the other fields, the prompt says Code snippet (<RET> to edit in external editor). What is <RET> in this case? Return/enter appears to only submit the snippet as it is.

    I have tried with $EDITOR both unset and set to vi.

    opened by tpoliaw 7
  • build on Android

    build on Android

    first thank you! works great on my pc, tried building on aarch64 and as title says, it fails to build "skim", yet I can (and have) built & installed "skim" already.

    opened by nerd190 6
  • WSL2 support

    WSL2 support

    Hello,

    I know Windows is not supported yet. But I tried to make it work on WSL2 nonetheless.

    I'm stuck on this issue:

    > the-way cp 2
    openssl x509 -noout -text -in
    Error: Can't open display: (null)
    Snippet #2 copied to clipboard
    

    This happens every time the-way tries to copy stuff to the SYSTEM clipboard. I'm assuming it's because wsl2 cannot do it natively. WSL2 can use Windows binaries tho, as specified here

    I am unsure why it tries to use a display. I hope anyone can shed some light about this.

    search seems to work properly. Altough with the cmdsave function, I get the same issue after I use search.

    ❯ the-way search
    find <path> -name <file>
    ✔ path · .
    ✔ file · '*.a'
    Error: Can't open display: (null)
    Snippet #1 copied to clipboard
    

    Please let me know if you need further testing.

    opened by wisewtf 5
  • Search within snippet contents

    Search within snippet contents

    As a pet user, searching snippet contents/body & descriptions at the same time in the same fzf pane interactively helps me find the snippet I'm looking for faster. Sometimes I remember a part of the snippet contents and not the description, and vice versa.

    So far I have been using (PR #68 that searches contents and descriptions, but it is not interactive. (afaik) there is no feature to perform an interactive grep on snippet contents.

    What are your thoughts about adding such a feature?

    opened by fhill2 5
  • the-way search: add option to use stderr for interface, directly output snippet

    the-way search: add option to use stderr for interface, directly output snippet

    When using the-way in the shell using the-way search, finding a snippet is very convenient, but then it gets copied to the clipboard.

    I'd much prefer an option that would just output the snippet to stdout. That way I could bind the-way to some key combination in bash and then directly get the snippet on the command line, maybe even automatically pressing enter. That would probably require the interface of the-way to print to stderr.

    enhancement 
    opened by kaspar030 5
  • Sync Error

    Sync Error

    Tried using the-way sync and pasting the Github token with gists enabled, but getting this returned:

    Error: 0: SyncError: "422 {"message":"Validation Failed","errors":[{"resource":"Gist","code":"missing_field","field":"files"}],"documentation_url":"https://docs.github.com/v3/gists/#create-a-gist"}"

    Suggestion: Make sure your GitHub access token is valid. Get one from https://github.com/settings/tokens/new (add the "gist" scope). Set it to the environment variable $THE_WAY_GITHUB_TOKEN

    Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it. Run with RUST_BACKTRACE=full to include source snippets.

    Also added the token into a env var as suggested, but same error is thrown.

    bug 
    opened by johnhayesio 5
  • Unsupported: cannot change the io buffer size across restarts

    Unsupported: cannot change the io buffer size across restarts

    Running any commands gives me this error: Unsupported: cannot change the io buffer size across restarts. please change it back to 8388608.

    I've tried deleting ~/.config/the-way to no avail. This is version 0.7.0 on NixOS.

    Running the same command with backtrace set to full gives:

    Error: 
       0: Unsupported: cannot change the io buffer size across restarts. please change it back to 8388608
    
      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
       1: color_eyre::config::HookBuilder::install::{{closure}}::h89493c7b19a69a32
          at <unknown source file>
       2: the_way::the_way::TheWay::start::hea72f08e14a0d57d
          at <unknown source file>
       3: the_way::main::ha4dc93d41b39356d
          at <unknown source file>
       4: std::rt::lang_start::{{closure}}::hf19916ed3db71252
          at <unknown source file>
       5: std::rt::lang_start_internal::h7d1b27a1580794aa
          at <unknown source file>
       6: main
          at <unknown source file>
       7: __libc_start_main
          at <unknown source file>
       8: _start
          at <unknown source file>
    

    Thanks!

    opened by numkem 5
  • poor readability of highlighted item in light themes

    poor readability of highlighted item in light themes

    Hello! I've tried all built-in light themes and they all suffer same issue, that is poor readability of highlighted item in fuzzy pane. Following is InspiredGitHub theme, but others light themes have more or less same issue.

    Screenshot-2020-07-02-at-20-43-32.png

    opened by vbauerster 4
  • Sync and backup of database

    Sync and backup of database

    The database directory contains several files:

    image

    I want to sync/backup the database across several machines, which of these files are important enough needs to be backed up for it to work? My current guess is that db should be enough, but the snap.* and conf also seem important. blobs is currently empty.

    Could you please explain what these files are? And for future users - maybe add a README.md to that directory to help guide people who'll wonder the same.

    opened by omertuc 4
  • (feature request) make better use of 'cmd' by allowing us to execute them.

    (feature request) make better use of 'cmd' by allowing us to execute them.

    Hi! (me again) As a new user, seeing both add and cmd makes me think they are two different functions, but it appears they achieve the same thing, except that using cmd saves us one extra step as it automatically tags the language as 'sh', which is certainly nice to have, but not really a needed feature. To make better use of this function, seeing as they are shell commands, allow us to execute them directly or clip them, that way our snippets are snippets and our cmds are one-liners! On the same note, if they wasnt automatically tagged 'sh' anymore, cmds could be one-liners written in any non-compiled language, for example, I use this great one-liner as a quick way to setup python:

    python3 -m ensurepip --default-pip && python3 -m pip3 install --upgrade pip setuptools wheel"
    

    And this one sets up Perls better pkg manager:

    curl -L https://cpanmin.us | perl - --sudo App::cpanminus
    

    Would be nice to add these as cmds that I can execute directly, rather than copy and paste them back into the terminal to use. Currently, my one-liners are saved as aliases, which isnt good as they are rarely used yet sourced everytime I open a new shell, when I do finally need to use them, I need to dig through a huge page of aliases, with the-way, I wouldnt need to do that anymore, plus aliases dont have metadata like the-way provides! (title, tags, description etc). Thank you once again!

    opened by nerd190 3
  • [Critical] Cargo error when install by yay

    [Critical] Cargo error when install by yay

    image

    The following error while install via yay

    Potential solution is adding a --locked flag to the cargo install command Ref: https://stackoverflow.com/questions/71332000/why-run-cargo-install-fails-with-error-edition-2021-is-unstable-though

    opened by madrigal1 2
  • I tried `the-way view 14` but my cursor gets stuck. When I press Ctrl+d it kills the whole terminal.

    I tried `the-way view 14` but my cursor gets stuck. When I press Ctrl+d it kills the whole terminal.

    Some of these, specifically those with serde crates, are easy to add as both import/export formats.

    I primarily would like to have markdown and plaintext export.

    sexps would be awesome too!

    plaintext / markdown would be difficult to support as an import format, but easier for export. What would be the difference between plaintext and running the-way view?

    It requires an index so I would need to write a for loop to get all the snippets out. I'd prefer to be able to just dump all the snippets to stdout or to dump snippets to stdout filtered by tags, etc... from the CLI directly.

    I tried the-way view 14 but my cursor gets stuck. When I press Ctrl+d it kills the whole terminal:

    2022-02-07-231638_1573x876_scrot

    I'm running the-way 0.15.0.

    Originally posted by @jgarte in https://github.com/out-of-cheese-error/the-way/issues/127#issuecomment-1032193663

    opened by jgarte 8
  • Support more export formats

    Support more export formats

    Here are some formats that might be relevant taken from jrnl for inspiration:

      --format TYPE         Display selected entries in an alternate format.
                            TYPE can be: boxed, dates, fancy, json, markdown, md,
                            pretty, short, tags, text, txt, xml, or yaml.
                            Optional parameters:
    

    Not all apply but having yaml, markdown, xml, and plain text output of all or a selected range of snippets might be useful.

    WDYT?

    opened by jgarte 3
  • Any chance of getting a human readable DB?

    Any chance of getting a human readable DB?

    Pet seems to no longer be maintained and is plagued by bugs and lacks configuration. But one of it strength is the human readable snippets toml files that can be edited. I only use it for shell snippets, since docker is a nightmare. One of my use cases is actually editing the toml file directly in sublime for what I need.

    Is there a way to do that now, or is that some extensive work?

    opened by seivan 1
  • Windows support

    Windows support

    Considering there appears to be PowerShell support (I know it's cross-platform now, but still) I'm surprised there's no Windows binaries available. Could you please add support for Windows?

    opened by ImportTaste 4
Releases(v0.18.0)
Owner
OutOfCheeseError
OutOfCheeseError
A list of crates with snippets used by me to learn more about Rust.

my-rust-examples This is a list of crates used by me to learn Rust. How to execute You can use a dependency called cargo-play: cargo install cargo-pla

Ronald 0 Jan 3, 2022
WIP. Goals: Treesitter highlighting, snippets, and a smooth intergration with neovim.

typst.nvim WIP. Goals: Tree-sitter highlighting, snippets, and a smooth integration with neovim. For the past week, I've been thinking what I want for

SeniorMars 66 Apr 9, 2023
Terminal UI for erhanbaris/smartcalc, a new way to do calculations on-the-fly

smartcalc-tui Terminal UI for erhanbaris/smartcalc, a new way to do calculations on-the-fly. From the README: Do your calculation on text based querie

Aaron Ross 12 Sep 14, 2022
ask.sh: AI terminal assistant that can read and write your terminal directly!

ask.sh: AI terminal assistant that read from & write to your terminal ask.sh is an AI terminal assistant based on OpenAI APIs such as GPT-3.5/4! What'

hmirin 5 Jun 20, 2023
Execute Rust code carefully, with extra checking along the way

cargo-careful cargo careful is a tool to run your Rust code extra carefully -- opting into a bunch of nightly-only extra checks that help detect Undef

Ralf Jung 240 Dec 28, 2022
Warp is a blazingly fast, Rust-based terminal that makes you and your team more productive at running, debugging, and deploying code and infrastructure.

Warp is a blazingly fast, Rust-based terminal that makes you and your team more productive at running, debugging, and deploying code and infrastructure.

Warp 10.4k Jan 4, 2023
Ox is a code editor that runs in your terminal

Ox editor Ox is a code editor that runs in your terminal. About The Project Ox is a code editor. It was written in Rust using ANSI escape sequences. I

null 0 Feb 3, 2022
Ask ChatGPT for a shell script, code, or anything, directly from your terminal 🤖🧠👨‍💻

ShellGPT Ask ChatGPT for a shell script, code, or anything, directly from your terminal ?? ?? ??‍?? Demo Install The binary is named gpt when installe

null 4 May 15, 2023
The dead easy way to use config files in your rust project

Configr The dead easy way to use config files in your project This will load a config.toml file if it exists, otherwise it will create the needed fold

Carsten Kragelund Jørgensen 4 Jul 1, 2022
An ascii webcam in your console, written as a way of learning rust.

asciicam An ascii webcam in your console, written as a way of learning rust. asciicam picture of me holding a basketball usage only linux is supported

Vilhelm Bergsøe 3 Nov 15, 2022
A simple, opinionated way to run containers for tests in your Rust project.

rustainers rustainers is a simple, opinionated way to run containers for tests. TLDR More information about this crate can be found in the crate docum

wefox 4 Nov 23, 2023
joshuto: ranger-like terminal file manager written in Rust.

joshuto: ranger-like terminal file manager written in Rust.

Jeff Zhao 1.1k Dec 30, 2022
A Minecraft mod manager for the terminal.

Hopper A Minecraft mod manager for the terminal. Donate High-level Goals modrinth mod searching modrinth mod installation curseforge api too? per-inst

Tebibyte Media 17 Dec 24, 2022
⚡️ Blazing fast terminal file manager written in Rust, based on async I/O.

Yazi - ⚡️ Blazing Fast Terminal File Manager Yazi ("duck" in Chinese) is a terminal file manager written in Rust, based on non-blocking async I/O. It

三咲雅 · Misaki Masa 189 Aug 1, 2023
Simple terminal file manager(vi-style keybindings) written in rust

rust-tfm rust-tfm is a terminal file manager written in rust heavily inspired by lf and ranger, and also inspired by suckless software. rust-tfm.mp4 F

Jiao ShiJie 9 Sep 26, 2023
Print your git contributions in your terminal, blazingly fast

Takoyaki Blazingly fast git contribution graph in your terminal Features ✔️ Customizable ✔️ Plugins to support a bunch of cloud based git repositories

kyeboard 13 Feb 6, 2023
Get your github contributions right in your terminal, blazingly fast!

GitColorScripts Get your github contributions right in your terminal! Installation Install via yay yay -S gitcolorscripts Install manually Download t

VoidCupboard 56 Jul 12, 2023
languagetool-code-comments integrates the LanguageTool API to parse, spell check, and correct the grammar of your code comments!

languagetool-code-comments integrates the LanguageTool API to parse, spell check, and correct the grammar of your code comments! Overview Install MacO

Dustin Blackman 17 Dec 25, 2022
A terminal ASCII media player. View images, gifs, videos, webcam, YouTube, etc.. directly in the terminal as ASCII art.

Terminal Media Player View images, videos (files or YouTube links), webcam, etc directly in the terminal as ASCII. All images you see below are just m

Max Curzi 36 May 8, 2023