Skip to content

Latest commit

 

History

History
474 lines (358 loc) · 13.5 KB

USAGE.md

File metadata and controls

474 lines (358 loc) · 13.5 KB
Raw

Usage

There are many specific usage situations which this document will cover. For more general usage, look at the Usage section in README.md.

Table of contents

Shell completions

You can generate shell completions with the generate-completion subcommand, source the generated file in your shell startup file (*rc) and completions will exist for tinty. Have a look at the README CLI section for more information about the command usage.

tinty generate-completion zsh > path/to/tinty-zsh-completion.sh

In your startup file (*rc) add the following:

source path/to/tinty-zsh-completion.sh

Completions in the repo

A shell completion generation via tinty doesn't include any dynamic values, meaning scheme names (such as base16-ocean) won't be completed typing tinty apply base. We've created modified completion script files for this reason so it can also generate the scheme names. Currently this is only supported for the bash completion file, but we plan to include the other shells too. You can find these completion files in contrib/completion.

How it works

There are some concepts which some of the following instructions will make use of.

current_scheme

~/.local/share/tinted-theming/tinty/current_scheme is a file which contains the name of the system prefix and name of the scheme (<system>-<scheme_name>), eg: base16-mocha. Whenever a scheme is applied through Tinty, this file is updated.

What does tinty apply do?

  1. tinty apply sets current_scheme.
  2. It then runs through the [[items]] in your `config.toml
  3. For each [[items]], or theme template, it copies the relevant theme to ~/.local/shared/tinted-theming/tinty and executes the hook property of the [[items]]. %f is a template variable that can be used in the hook, e.g., hook = "cp -f %f ~/.config/alacritty/colors.yml.

tinty apply can also be used without a theme template. The config.hooks property will execute the array of hooks regardless of template. This can be useful for when an application is using base16 (or another supported system) and you just want to write tinty current to a file.

Once you understand the functionality and the lifecycle, you can do a lot with it.

Sourcing scripts that set environment variables

General config.toml hooks can be used to source and execute scripts, but due to the way shell sub-processes work, the scripts sourced by Tinty can't set your current shell session's environment variables. There is a workaround for this specific issue.

  1. Create a function which executes tinty with all the same arguments
  2. Check for any *.sh files in the active Tinty themes directory
  3. Source any matching files

The following script does that. Add it to your shell startup file (*rc):

# Tinty isn't able to apply environment variables to your shell due to
# the way shell sub-processes work. This is a work around by running
# Tinty through a function and then executing the shell scripts.
tinty_source_shell_theme() {
  tinty $@
  subcommand="$1"

  if [ "$subcommand" = "apply" ] || [ "$subcommand" = "init" ]; then
    tinty_data_dir="${XDG_DATA_HOME:-$HOME/.local/share}/tinted-theming/tinty"

    for tinty_script_file in $(find "$tinty_data_dir" -maxdepth 1 -type f -name "*.sh"); do
      . $tinty_script_file
    done

    unset tinty_data_dir
  fi

  unset subcommand
}

if [ -n "$(command -v 'tinty')" ]; then
  tinty_source_shell_theme "init"

  alias tinty=tinty_source_shell_theme
fi

Note: Make sure to swap out $tinty_data_dir with the path to your custom data directory if you don't use the default of Tinty. Tinty stores themes to $XDG_DATA_HOME based on XDG Base Directory specification by default.

Use your own schemes

To use your own schemes, create a custom-schemes/<scheme_system>/your-scheme-name.yaml file in your data-dir (Run tinty config --data-dir-path to get the path to your data-dir) - where <scheme_system> is the system you use. Currently we support scheme_system base16 and base24. After you've added your scheme, make sure it exists correctly by running tinty list --custom-schemes. If you do not see it listed, something is wrong and Tinty will not apply it.

If everything works as expected, tinty apply base16-your-scheme-name.yaml should apply your scheme.

mkdir "$(tinty config --data-dir-path)/custom-themes/base16"
cp path/to/your/base16-your-scheme.yaml "$(tinty config --data-dir-path)/custom-themes/base16/your-scheme.yaml"
tinty list --custom-schemes # Should show your scheme
tinty apply base16-your-scheme

Alacritty

[[items]]
path = "https://github.com/tinted-theming/tinted-alacritty"
name = "tinted-alacritty"
themes-dir = "colors" # or "colors-256"
hook = "cp -f %f ~/.config/alacritty/colors.toml && touch ~/.config/alacritty/alacritty.toml"

The hook copies the applied theme contents to ~/.config/alacritty/colors.toml and then does a touch on ~/.config/alacritty/alacritty.toml to alert alacritty that the config has been updated and it should rerender with the new config.

Make sure your alacritty.toml contains the import to the colors.toml file by including this line:

import = ["~/.config/alacritty/colors.toml"]

Shell

When Tinty does not have any [[items]] set up in config.toml, Tinty automatically uses tinted-shell as a default [[items]]. If you have added anything to [[items]], you must also add tinted-shell there too if you want it to be part of the templates you apply.

Add the following to your config.toml:

[[items]]
path = "https://github.com/tinted-theming/tinted-shell"
name = "tinted-shell"
themes-dir = "scripts"
hook = ". %f"

tinted-shell does set some environment variables in the script, but it's not necessary for shell styling. If you still want access to these variables, you will need to execute the tinted-shell theme script in your current shell session. Have a look at Sourcing scripts that set environment variables

Vim or Neovim

There are two different ways you could have vim hooked up to Tiny:

  1. Have base16-vim installed in your vim setup and run :colorscheme <THEME_NAME> when Tinty applies a scheme
  2. Have vim source the .vim theme file when Tinty applies a scheme

With base16-vim setup in Vim/Neovim

This doesn't require any setup in your Tinty config.toml.

  1. Follow the [base16-vim] setup installation instructions.
  2. Have vim read the current_scheme file and set the vim colorscheme with :colorscheme <DATA_IN_CURRENT_SCHEME> by adding the following to your vim setup. The following Lua or VimScript reads the current_scheme file when you set your focus to vim and if the theme is different to the one already set, it sets it:

Neovim (Lua)

local default_theme = "base16-oceanicnext"

local function get_tinty_theme()
  local theme_name = vim.fn.system("tinty current &> /dev/null && tinty current")

  if vim.v.shell_error ~= 0 then
    return default_theme
  else
    return theme_name
  end
end


local function handle_focus_gained()
  local new_theme_name = get_tinty_theme()
  local current_theme_name = vim.g.colors_name

  if current_theme_name ~= new_theme_name then
    vim.cmd("colorscheme " .. new_theme_name)
  end
end

local function main()
  vim.o.termguicolors = true
  vim.g.tinted_colorspace = 256
  local current_theme_name = get_tinty_theme()

  vim.cmd("colorscheme " .. current_theme_name)

  vim.api.nvim_create_autocmd("FocusGained", {
    callback = handle_focus_gained,
  })
end

main()

Vim

let g:default_theme = "base16-oceanicnext"

function! GetTintyTheme()
  let l:theme_name = system("tinty current &> /dev/null && tinty current")

  if v:shell_error != 0
    return g:default_theme
  else
    return l:theme_name
  endif
endfunction

function! HandleFocusGained()
  let l:new_theme_name = GetTintyTheme()
  let l:current_theme_name = g:colors_name

  if l:current_theme_name != l:new_theme_name
    execute "colorscheme " . l:new_theme_name
  endif
endfunction

function! Main()
  set termguicolors
  let g:tinted_colorspace = 256
  let l:current_theme_name = GetTintyTheme()

  execute "colorscheme " . l:current_theme_name

  augroup TintyThemeChange
    autocmd!
    autocmd FocusGained * call HandleFocusGained()
  augroup END
endfunction

call Main()

Without base16-vim setup in Vim/Neovim

  1. Add base16-vim to Tinty config.toml
  2. Have vim source the .vim colorscheme file when you focus Vim/Neovim.
[[items]]
path = "https://github.com/tinted-theming/base16-vim"
name = "base16-vim"
themes-dir = "colors"

Neovim (Lua)

local theme_script_path = vim.fn.expand("~/.local/share/tinted-theming/tinty/base16-vim-colors-file.vim")

local function file_exists(file_path)
  return vim.fn.filereadable(file_path) == 1 and true or false
end

local function handle_focus_gained()
  if file_exists(theme_script_path) then
      vim.cmd("source " .. theme_script_path)
  end
end

if file_exists(theme_script_path) then
  vim.o.termguicolors = true
  vim.g.tinted_colorspace = 256

  vim.cmd("source " .. theme_script_path)

  vim.api.nvim_create_autocmd("FocusGained", {
    callback = handle_focus_gained,
  })
end

Vim

let theme_script_path = expand("~/.local/share/tinted-theming/tinty/base16-vim-colors-file.vim")

function! FileExists(file_path)
  return filereadable(a:file_path) == 1
endfunction

function! HandleFocusGained()
  if FileExists(g:theme_script_path)
    execute 'source ' . g:theme_script_path
  endif
endfunction

if FileExists(theme_script_path)
  set termguicolors
  let g:tinted_colorspace = 256
  execute 'source ' . theme_script_path
  autocmd FocusGained * call HandleFocusGained()
endif

tmux

Add to Tinty config.toml

[[items]]
path = "https://github.com/tinted-theming/tinted-tmux"
name = "tinted-tmux"
# Check if tmux is in use and if it is, reload the config file
hook = "tmux run 2> /dev/null && tmux source-file %f"
themes-dir = "colors"

Without Tinty template setup

If you're using tinted-tmux as a tmux tpm plugin, you can add add the following to your tmux.conf:

run-shell "tmux set-option -g @tinted-color $(tinty current)"

And add the following to Tinty config.toml:

hooks = ["tmux source-file /path/to/tmux.conf"]

fzf

Using shell ANSI colors

There is a special fzf theme file in tinted-fzf created for using the shell's ANSI colors to style fzf. If you are using tinted-shell

Using theme

Due to the way shell sub-processes work, Tinty isn't able to set shell environment variables in your session, which is how fzf themes are applied, so a workaround is needed.

1. Add the following to your config.toml:

[[items]]
path = "https://github.com/tinted-theming/tinted-fzf"
name = "tinted-fzf"
themes-dir = "sh"
# Or for fish shell
# themes-dir = "fish"

2. Source the fzf theme script files in your shell

Have a look at Sourcing scripts that set environment variables section. Once you've implemented that, your fzf theme should be updating correctly when you run tinty init or tinty apply base16-mocha or some other theme name.

Add to Tinty config.toml

[[items]]
path = "https://github.com/tinted-theming/tinted-fzf"
name = "tinted-fzf"
hook = ". %f"
themes-dir = "sh"
# Or for fish shell
# themes-dir = "fish"

Iterm2

[[items]]
path = "https://github.com/tinted-theming/tinted-iterm2"
name = "tinted-iterm2"
hook = "sh %f"
themes-dir = "scripts"
supported-systems = ["base16", "base24"]

bat

bat has an integration with tinted-shell and another option to allow ANSI colors to be used. The available bat theme names for this are base16-256 and ansi.

  • bat --theme="base16-256" if you're using the default Tinty or tinted-shell with Tinty.
  • bat --theme="ansi" if you're using another shell template theme with Tinty.

Set the alias in your .*rc file to make sure this is run by default whenever bat is executed.

alias bat="bat --theme='base16-256'"

Qutebrowser

To add base16-qutebrowser support, add the following to Tinty config.toml:

[[items]]
path = "https://github.com/tinted-theming/base16-qutebrowser"
name = "base16-qutebrowser"
themes-dir = "themes/default" # Or "themes/minimal"
hook = "cp -f %f ~/.config/qutebrowser/config.d/colorscheme.py"
theme-file-extension = ".config.py"