Oxidizer.sh

Minimalistic & Extensible Dotfile Management Solution using Rust Toolchains (PRs and Forks are welcome !)

English | 简体中文

Let's Oxidize Development Environments

1. Get Started

For macOS / Linux

# define path for Oxidizer
export OXIDIZER=$HOME/oxidizer

git clone --depth=1 https://github.com/ivaquero/oxidizer.sh.git $OXIDIZER
bash $OXIDIZER/install.sh

Note that Homebrew is an essential dependency for Oxidizer on macOS / Linux. For China mainland users, you may set BREW_CN variable to install Homebrew through domestic mirror

export BREW_CN=1

For Windows

# define path for Oxidizer
$env:OXIDIZER = "$env:USERPROFILE\oxidizer"

git clone --depth=1 https://github.com/ivaquero/oxidizer.sh.git $env:OXIDIZER
. $env:OXIDIZER\install.ps1

Note that Scoop is an essential dependency for Oxidizer on Windows. For China mainland users, you may set SCOOP_CN variable to install Scoop through domestic mirror

$env:scoop_mirror = 1

After installation, you might personalize your preference in custom.sh (check demo-custom.sh). Open custom.sh by following command

ef ox

To keep up the updates, simply use upox function.

2. Philosophy

Oxidizer is origenally designed for non-administrator users. It quickly sets up a minimal but powerful coding environment, and it aims to provide with following features:

• Cross-Platform (Mainly Rust Tool chains)
• Minimal dependencies & Minimal Installation
• Extensible Architecture
• Unified Interface & Smooth Usage
• Super-Fast! (Loading time < 1 s)

3. Oxidization Progress

3.1. Command Line Replacement (Recommand all following)

☑️ means required in the installation.

• [x] Use bat instead of cat
• [x] Use fd instead of find
• [x] Use gitui instead of lazygit
• [x] Use lsd instead of ls
• [x] Use ls --tree instead of tree
• [x] Use ripgrep instead of grep
• [x] Use sd instead of sed
• [x] Use tealdeer instead of tldr or man
• [x] Use zoxide instead of cd or z.lua
• [ ] Use bottom instead of top or htop
• [ ] Use dust instead of du
• [ ] Use tokei instead of cloc

3.2. Software Replacement

• [ ] Use WezTerm instead of iTerm2 or Windows Terminal (not required, but strongly recommended)
• [ ] Use Helix instead of NeoVim
• [ ] Use Nushell instead of Zsh or Powershell

For Nushell: Its nu language is new and will add learning cost. If you'd love to try something new, see oxidizer-next.

3.3. Other Useful Rust Tools

• [x] pueue: Command-line task management tool for sequential and parallel execution of long-running tasks.
• [x] hyperfine: Command-line benchmarking tool
• [ ] delta: A syntax-highlighting pager for git, diff, and grep output
• [ ] mdbook: A utility to create modern online books from Markdown files.

3.4. Summary of Plugins

Oxidizer is designed to be extensible, you can personalize PLUGINS in custom.sh to load the plugins by your need.

Of course, you are allowed to write your own plugins, see 10. Writing A Plugin for details.

✅: complete functionality 🚧: partial functionality 🕒: basic functionality, needs more features ❌: not exist

¹: Currently, on Linux only provide with Ubuntu-specific shortcuts.

Oxidizer uses Homebrew or Scoop to manage packages and softwares to bypass the requirement of administrator privilege.

For Linux users, you can try to add Homebrew tap Hombrew-Linux to install GUI Applications.

4. File Management

• ff
  • refresh file by source
• ef
  • file: edit by $EDITOR (default: VSCode)
• bf
  • file: browse by bat / cat
  • folder: browse by lsd / ls
• ipf
  • file: overwrite system configurations by customized (backup) files
• epf
  • file: export system configurations to back up folder
• iif
  • file: overwrite system configurations in by Oxidizer defaults.

For example, if you want to edit ~/.zshrc, you can type ef zs.

When you use epf zs, ~/.zshrc will be copied and save in $BACKUP/shell folder, where $BACKUP is the backup path that can be personalized in $OXIDIZER/custom.sh. As mentioned in 1. Get Started, you can open custom.sh simply by ef ox.

The table below shows the informatioin of specific configuration files.

_ denotes folder

5. Software management

• back_*
  • file: export package/extension configurations to $BACKUP folder
• up_*
  • file: update package/extension configurations in $BACKUP folder to system
• init_*
  • file: install by package/extension configuration files in $Oxygen/install folder

More specifically

• back_conda: backup Conda package list $BACKUP folder
• back_node: backup NodeJS package list to $BACKUP folder
• back_julia: backup Julia package list $BACKUP folder
• back_texlive: backup TeXLive collection list $BACKUP folder
• back_vscode: backup VSCode extension list $BACKUP folder

update_* and init_* work similarly.

5.1. NeoVim

For NeoVim, a pure Lua configuration (using init.lua ) is recommended instead of classic Vim configuration (using init.vim ).

However, if you would like to the native vim but haven't configure it, you can try Oxidizer's default configuration by iif vi.

5.2. TeXLive

6. Package Management

Oxidizer aims to provide a unified interface for all package manager-related commands to reduce typing and memory burden of command-line users.

Particularly, Oxidizer provides with two groups of experimental functions with suffix p for installing and downloading packages in parallel

• brew: bisp, biscp, bupp, bupap
• scoop: sisp, supp

For example, when you have more than 1 packages to install, instead of using bis [pkg1] [pkg1], you can use bisp [pkg1] [pkg1] then the packages will be downloaded and installed in parallel.

Similary, biscp, bupp, bupap are the parallel version of bisc, bup, bupa, respectively.

Before using parallel functions, pueue service need to be enabled by

# All OS
pueued -d
# or macOS / Linux
bss pu

Some package managers also have functionality of project management

Some of package manager shortcuts are included in corresponding system plugins.

• zsh-macos [zsm]: auto-loaded, contains mas.
• zsh-ubuntu [zsub]: contains apt
• pwsh-windows [pswd]: auto-loaded, contains winget, wsl.

6.1. Homebrew

• [x] Integrated Aria2 to download Homebrew Casks

• [x] Enable Homebrew installation by using pre-download installers

• bis: brew install

• bris: brew reinstall

suffix c is a flag to specify brew commands only work on casks

• bisc: brew install --cask
• brisc: brew reinstall --cask
• bupc: brew upgrade --cask

suffix a is for all which will force brew to upgrade every cask including ones with auto_update flags

• bupa: brew upgrade --greedy

• bdl: download brew cask by aria2

• brp: replace brew cache file by pre-downloaded file

• bmr: using brew mirror

• bmrq: reset brew git source to official repositories, q is for quit.

6.2. Conda

Note that the conda plugin is based on mamba (a parallel version of conda) and conda-tree, so you need to install mamba by

conda install -c conda-forge mamba conda-tree

Besides the shortcuts mentioned above in 6. Package Management, the conda plugin also provides with Conda environment management shortcuts which start with ce

• ceat: activate environment
  • $1 length = 0: activate base env
  • $1 length = 1 or 2: activate predefined env Conda_Env
  • $1 length > 2: activate new env

Conda_Env can be personalize in custom.sh

For example, if you conda environment name is hello, you can set

# macOS / Linux
Conda_Env[h]="hello"
# Windows
$global:Conda_Env.h = "hello"

then, you will be able to manipulate the environment by

# create environment
cecr h
# remove environment
cerm h
# update all packages in the specific environment
cup h
# list all packages in the specific environment
cls h

• cerat: reactivate environment, works live ceat
• ceq: quit environment ( q is for kill/quit )
• cecr: create
• cerm: remove environment, works live ceat but won't remove base env
• cels: environment list
• cesd: change environment's conda-forge subdir
• ceep: export environment

7. Project & Task Management

Oxidizer's task & system management follows the same phylosopy of package management, i.e. to provide unified interfaces to faciliate workflows.

7.1. Git

• [x] delete ignored files in .gitignore: gig
• [x] find fat blob files: gjk
• [ ] integration of git filter-repo command
  • [x] clean files by size bigger than gcl -s
  • [x] clean files by id gcl -i
  • [x] clean files by path gcl -p

7.2. Docker

7.3. Pueue

7.4. Homebrew Services

8. Utils Management

8.1. Formats

• [x] Convert markdown: mdto
  • [x] to PDF with Unicode (for CJK)

mdto [filename] [format]

8.2. Widgets

• [x] Weather report (using wttr/in)

wtr [location]

9. System Management

9.1. macOS

• update: update system
• clean
  • clean: empty trash
  • clean bdl: clean homebrew downloaded files
  • clean cc: clean cache files in $HOME/Library/Caches/
  • clean log: clean logs
• allow: allow installation of uncertified apps

9.2. Linux

10. Writing A Plugin

A plugin in Oxidizer is refered as Oxygen, a key-value object whose key starts with oxp.

For a Vim plugin on macOS / Linux, you can write

Oxygen[oxpvi]=plugin_path

And add the key of Oxygen into PLUGINS object in custom.sh like

PLUGINS=(oxp1 oxp2 oxpvi)

For Windows users, do these in a similar way

$global:Oxygen.oxpvi = "plugin_path"

And add it into PLUGINS object in custom.ps1

10.1. Config Files

A system / software / tool configuration file in Oxidizer is refered as Element, set it like what you do with Oxygen

# macOS / Linux
Element[vi]=$HOME/.vimrc
# Windows
$global:Element.vi = "$env:USERPROFILE/.vimrc"

If you need to set a folder in Oxygen, plus a _ as the suffix of the key.

# macOS / Linux
Element[vi_]=$HOME/.vim
# Windows
$global:Element.vi_ = "$env:USERPROFILE/vim"

10.2. Backup Files

A backup file in Oxidizer is refered as Oxide whose key starts with bk, set it like

# macOS / Linux
Oxide[bkvi]=$BACKUP/.vimrc
# Windows
$global:Oxide.bkvi = "$env:BACKUP/.vimrc"

Do remember the key in Oxygen, Element, Oxide must be consistent: oxvi, vi, bkvi works, others don't.

11. Credits

• Mario Catuogno's Clean-macOS
• Mike McQuaid's dotfiles

12. License

This work is released under the GPL-v3 license.