README.md

Oxidizer

A Simple & Extensible Dotfile Manager That Unifies Your Terminal Operations

English | 简体中文

Let's Oxidize Development Environments

1. Get Started

For macOS / Linux (Intel)

export OXIDIZER=$HOME/oxidizer
git clone --depth=1 https://github.com/ivaquero/oxidizer.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

Note that Oxidizer only support limited functionality on Linux-on-ARM yet.

For Windows

$env:OXIDIZER = "$HOME\oxidizer"
git clone --depth=1 https://github.com/ivaquero/oxidizer.git $env:OXIDIZER; . 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

For Cmder users, you need to remove the -Options ReadOnly from Set-Item -Path function:\prompt -Value $Prompt -Options ReadOnly in the last line of %CMDER_ROOT%\vendor\profile.ps1.

After installation, you might personalize your preference in custom.sh, check defaults.sh. Open custom.sh or custom.ps1 by following command

edf ox

To keep up the updates, simply use upox function.

2. Motivation

Oxidizer is originally designed for non-administrator users. It saves your time from repetitive and tedious setups of coding environments, and it aims to provide with following features:

• Cross-Platform (mainly Rust toolchains)
• Minimal Dependencies & Minimal Installation
• Extensible Architecture
• Unified Interface & Smooth Usage
• Super-Fast! (loading time < 1 s)

2.1. CLI Tools Replacement

☑️ means required in the installation.

• coreutils
  • Use bat instead of cat
  • Use lsd instead of ls
  • Use uutils-coreutils instead of coreutils
• non-coreutils
  • Use dust instead of du
  • Use fd instead of find
  • Use ripgrep instead of grep
  • Use sd instead of sed
  • Use tlrc instead of tldr or man
  • Use zoxide instead of cd or z
  • Use hyperfine instead of time
  • Use starship instead of powerline10k or ohmyposh
  • Use tokei instead of cloc

2.2. GUI Tools Replacement

• Use WezTerm or alacritty instead of iterm2 or windows terminal

WezTerm is more recommended because it has a built-in multiplexer.

2.3. Other Useful Rust Tools

• onefetch: Command-line Git information tool
• yazi: Termianl file manager
• kondo: A tool to clean dependencies and build artefacts from your projects
• ouch: Painless compression and decompression tool
• sniffnet: Application to monitor Internet traffic

2.4. Summary of Plugins

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

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

The plugins are hosted in oxplugins as well as oxplugins-powershell.

Plugin Abbr.	Category	Support	Must?
oxpbg	Better to Have	Git
oxpom	OS Shortcuts	macOS	✓
oxpod	OS Shortcuts	Debian-Based Systems	✓
oxpor	OS Shortcuts	RedHat-Based Systems	✓
oxpow	OS Shortcuts	Windows (include winget)	✓
oxppb	Package Manager	Homebrew (macOS & Linux)	✓
oxpps	Package Manager	Scoop (Windows)	✓
oxppc	Package Manager	Conda (Multi-Languages)
oxppn	Package Manager	NPM (JavaScript)
oxpppx	Package Manager	Pixi (Multi-Languages)
oxpptl	Package Manager	tlmgr (TeXLive)
oxpljl	Programming Language	Julia
oxplrb	Programming Language	Ruby (include gem)
oxplrs	Programming Language	Rust (include cargo, rustup)
oxpcbw	App CLI	Bitwarden
oxpces	App CLI	Espanso
oxpcjr	App CLI	Jupyter (notebook / lab, book)
oxpcol	App CLI	Ollama
oxpcvs	App CLI	VSCode
oxpuf	System Utils	File Operation	✓
oxpufm	System Utils	Formats Conversion
oxpunw	System Utils	Network Configuration	✓
oxptwr	Terminal Utils	Weather (wttr-based)
oxptzj	Terminal Utils	Zellij (macOS & Linux)
oxpxns	Extra Utils	Notes Apps (Obsidian & Logseq)

To load a plugin, simply add its abbreviation into the OX_PLUGINS array of ~/oxidizer/custom.sh, like

OX_PLUGINS=(
    oxpbg
    oxpufm
    oxplrs
)

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

3. File Management

• rff
  • refresh file by source
• edf
  • edit file by $EDITOR (default: VSCode)
• brf
  • file: browse by bat / cat
  • folder: browse by lsd / ls
• rdf (alias: ipf, means import file)
  • reduce file: overwrite configuration file by backup (customized) file
• oxf (alias: epf, means export file)
  • oxidize file: backup configuration file to backup folder
• clzf (alias: iif, means initialize file)
  • catalyze file: overwrite configuration file by Oxidizer defaults
• ppgf
  • propagate file: backup Oxidizer defaults to backup folder

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

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

The table below lists the information of specific configuration files:

Origin	File Abbr.	File	in Plugin
oxidizer	ox	custom.sh
zsh	zs	.zshrc	built-in
starship	ss	starship.toml	built-in
wezterm	wz	wezterm.lua	custom.sh
debian	sc	/etc/apt/sources.list	oxpod
scoop	w	config.json	oxpps
winget	w	settings.json	oxpow
git	gi	.gitignore	oxpbg
git	g	.gitconfig	oxpbg
conda	c	.condarc	oxppc
javascript	jsx	js-pkgs.txt	oxppn
npm	n	.npmrc	oxppn
latex	tl	texlive-pkgs	oxpptl
cargo	cg	config.toml	oxlrs
rustup	rs	settings.toml	oxlrs
espanso	es	default.yml	oxpces
espanso	esb	match/base.yml	oxpces
espanso	esx_	match/packages	oxpces
vscode	vs	settings.json	oxpcvs
vscode	vsk	keybindings.json	oxpcvs
vscode	vss_	snippets	oxpcvs
vscode	vsx	vscode-pkgs.txt	oxpcvs
jupyter	jr	jupyter_notebook_config.py	oxpcjr
zellij	zj	config.kdl	oxptzj
zellij	zjl_	layouts	oxptzj

_ denotes a folder, and you can check these abbreviations closely by brf [Plugin Abbr.] or edf [Plugin Abbr.].

Oxidizer uses ouch to deal with compression and decompression, and provides with 3 shortcuts

• zpf: compress file
• uzpf: decompress file
• lzpf: list items in the compressed file

4. Software Information Management

back_* and up_* work for brew, scoop, conda, vscode (only for windows), julia, tlmgr, npm. clean_* works for brew and conda.

• back_*
  • file: export package/extension info into $OX_BACKUP folder
• up_*
  • file: install packages/extensions by predefined files in $OX_BACKUP
• clean_*
  • file: clean package/extension info by predefined files in $OX_BACKUP folder

5. 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.

Suffix	Action	brew b	scoop s	conda c	npm n	cargo cg	rustup rs	julia jl	pixi px	gem rb	tlmgr tl
*h	help	✅		✅	✅	✅	✅	✅	✅	✅	✅
*cf	config	✅		✅	✅				✅
*is	install	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
*us	uninstall	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
*up	update	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
*ups	update self	✅	✅								✅
*ls	list	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
*lv	leaves	✅	✅	✅	✅	✅		✅	✅
*sc	search	✅	✅	✅	✅	✅			✅	✅
*cl	clean	✅	✅	✅	✅	✅		✅	✅	✅
*if	info	✅	✅	✅	✅	✅					✅
*st	status	✅	✅		✅			✅
*ck	check	✅	✅	✅	✅	✅	✅			✅	✅
*pn	pin	✅	✅					✅
*upn	unpin	✅	✅					✅
*dp	depends	✅	✅	✅		✅		✅		✅
*dpr	needs			✅				✅
*xa	add repo	✅	✅	✅
*xrm	remove repo	✅	✅	✅
*xls	list repo			✅

Some package managers also have functionality of project management

Suffix	Action	brew b	scoop s	conda c	npm n	cargo cg	rustup rs	julia jl	pixi px	gem rb
*ii	init			✅	✅	✅			✅
*cr	create	✅	✅		✅	✅
*b	build					✅		✅		✅
*r	run			✅	✅	✅	✅	✅	✅
*ed	edit	✅
*ct	cat	✅	✅							✅
*ln	link	✅
*ts	test	✅			✅	✅		✅
*au	audit	✅			✅
*fx	fix	✅			✅	✅
*pb	publish				✅	✅

Some of the package managers shortcuts are included in corresponding system plugins.

• ox-os-macos: autoloaded, contains alias and functions for mas
• ox-os-debians: autoloaded, contains alias and functions for apt
• ox-os-windows: autoloaded, contains alias and functions for winget and wsl

Suffix	Action	mas m	apt a	winget w	wsl wl
*h	help	✅	✅	✅	✅
*is	install	✅	✅	✅	✅
*us	uninstall	✅	✅	✅	✅
*up	update	✅	✅	✅	✅
*ups	update self		✅	✅	✅
*ls	list		✅	✅	✅
*lv	leaves
*sc	search	✅	✅
*cl	clean		✅	✅	✅
*if	info	✅	✅	✅
*st	status	✅
*ck	check		✅
*dp	depends		✅
*xa	add repo		✅	✅
*xrm	remove repo		✅	✅
*xls	list repo		✅	✅

5.1. Homebrew

• 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

• brp [cask]: replace brew cache file by pre-downloaded file

5.2. Conda

Note that some shortcuts of the ox-conda plugin is based on the package conda-tree that you need to install

conda install -c conda-forge conda-tree

Besides the shortcuts mentioned above in 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 OX_CONDA_ENV
  • $1 length > 2: activate new env

OX_CONDA_ENV can be personalized in custom.sh

For example, assume your environment's name is hello, you can set

# macOS / Linux
OX_CONDA_ENV[h]="hello"
# Windows
$Global:OX_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
• cedf: compare packages between conda environments
• cern: renames an existing environment
• cesd: change environment's conda-forge subdir
  • i: for osx-64 or linux-64 or win-64
  • a: for osx-arm64 or linux-aarch64 or win-arm64
  • p: for ppc64le
  • s: for linux-s390x
• ceep: export environment

6. Project Management

6.1. Git

• gclhs: delete commit history

for aliases, check .gitconfig in defaults folder by edf oxg

7. Further Reading

• Service Management
• Project Management
• Utility Management
• System Management
• Writing A Plugin

8. Credits

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

9. License

This work is released under the GPL-v3 license.