Getting Started with Winuxsh

A short walkthrough from zero to a working prompt with git status.

1. Build or download

git clone https://github.com/unixwin/winuxsh.git
cd winuxsh
cargo build --release

After building, the binary is at target\release\winuxsh.exe. You can run it directly, or add target\release to your user PATH using your normal Windows environment settings:

target/release/winuxsh.exe

If you are using the release zip, winuxsh automatically runs the activation script on first start when command links are missing:

winuxsh winuxcmd/activate-winuxcmd.sh

That creates local command links inside winuxcmd/, so ls, cat, and friends resolve normally. Once the links exist, startup skips activation.

2. Start the shell

winuxsh

You should see something like:

user@DESKTOP C:\Users\you
%

Type exit or press Ctrl+D to quit.

3. See the git prompt

cd into any git repository:

cd C:\Users\you\repo
# if inside a repo, the prompt changes:
user@DESKTOP C:\Users\you\repo  git:(main) ●1 ✚2 ?1
%

Symbols at a glance:

SymbolMeaning
●NN files staged for commit
✚NN files modified but unstaged
?NN untracked files
↑NN commits ahead of upstream
↓NN commits behind upstream
⚑NN stashes saved
✖NN merge conflicts

The branch name is green when the tree is clean, yellow when dirty.

4. Try some commands

pwd                                  # prints C:/Users/you/repo
ls -la                               # Unix-style listing
echo "hello from $USER"
for i in 1 2 3; do echo $i; done
if [ -f Cargo.toml ]; then echo "yep"; fi
cat Cargo.toml | grep name
grep -n "fn main" src/main.rs

Windows paths work directly:

ls C:\Windows\System32\drivers\etc
ls D:/Projects
cd "C:\Program Files"

Multiline blocks work naturally:

for f in *.toml; do
  echo "found $f"
done

5. Try git completions

git ad<Tab>                # completes to `git add`
git commit -<Tab>           # shows flags: --message, --all, --amend
git push --fo<Tab>          # completes to --force
git branch -<Tab>           # shows -d, -D, -m, -v, -a, -r

6. Set up your config

Create ~/.winuxshrc for interactive shell code, plugin selection, and theme selection:

WINUXSH_THEME=minimal
WINUXSH_THEME_PLUGIN=theme-minimal
WINUXSH_PROMPT_SYMBOL="❯"
export WINUXSH_THEME WINUXSH_THEME_PLUGIN WINUXSH_PROMPT_SYMBOL

WINUXSH_PLUGINS=(prompt-core git)

if [ -z "${HOME:-}" ] && [ -n "${USERPROFILE:-}" ]; then
  HOME="$USERPROFILE"
  export HOME
fi

if [ -z "${WINUXSH:-}" ]; then
  WINUXSH="$HOME/.oh-my-winuxsh"
  export WINUXSH
fi

[ -f "$WINUXSH/oh-my-winuxsh.winux" ] && . "$WINUXSH/oh-my-winuxsh.winux"
winuxsh_prompt_use_template "{cwd} {git_prompt}{prompt_char} " "{time} " 2>/dev/null || true

export EDITOR=vim
alias ll='ls -la'
alias la='ls -a'
alias gst='git status'
alias gco='git checkout'
alias gl='git log --oneline --graph --decorate --all'

hello() {
  echo "hello from winuxsh"
}

~/.winuxshrc is sourced only for the interactive REPL and the -C one-shot REPL command path. It does not run for winuxsh -c ..., script files, or stdin script execution, so agent and CI surfaces stay deterministic.

~/.winshrc is a legacy compatibility fallback and is used only when ~/.winuxshrc is absent. ~/.winshrc.toml remains supported for legacy and managed structured state such as plugin CLI enable/disable records, migration blocks, completion overrides, test isolation, and advanced machine-editable settings. Prefer ~/.winuxshrc for normal interactive customization.

6b. Prompt and theme plugins

Themes are official plugins. To use a Powerlevel-style theme, switch the theme plugin in ~/.winuxshrc:

WINUXSH_THEME=p10-lean
WINUXSH_THEME_PLUGIN=theme-p10-lean
WINUXSH_PLUGINS=(prompt-core git)

Useful bundled theme plugins include theme-minimal, theme-classic, theme-pure, theme-robbyrussell, theme-p10-lean, theme-p10-classic, theme-p10-rainbow, and theme-p10-pure. Theme TOML assets support named colours, 256-colour indexes, and true-colour #RRGGBB foreground/background values plus bold, italic, underline, and dimmed flags.

Prompt templates use the public prompt-core API:

winuxsh_prompt_use_template "{cwd} {git}{prompt_char} " "{status}{time} "

Available template tokens include {cwd}, {cwd_base}, {user_host}, {git}, {git_prompt}, {status}, {time}, {command_execution_time}, {newline}, and {prompt_char}. The Git prompt snapshot is refreshed during startup/precmd so late Git work warms the next prompt instead of redrawing the line the user is typing on.

7. Import your .zshrc (optional)

If you already have a .zshrc with Oh My Zsh, let winuxsh inspect it:

winuxsh --zsh-compat-report
winuxsh --zsh-compat-import-plan

Review the plan. If it looks safe (it scans, does not blindly source):

winuxsh --zsh-compat-import-apply
winuxsh --zsh-compat-doctor

8. Official plugin bundle

Winuxsh has a built-in plugin system. oh-my-winuxsh is the official bundled plugin distribution, not an Oh My Zsh fork and not zsh plugin support. It ships first-party packs such as git, docker, kubectl, npm, zoxide, direnv, dotenv, fzf, prompt presets, and keybinding presets.

The normal interactive shape is the ~/.winuxshrc plugin list shown above. When winuxsh plugin enable/disable or migration tooling needs structured state, it writes managed records to ~/.winshrc.toml, for example:

[plugins]
enabled = true
bundles = ["oh-my-winuxsh"]
load = ["git", "prompts", "keybindings"]

[plugins.git]
enabled = true
permissions = ["shell:source", "cwd:read", "process:run:git"]

[plugins.zoxide]
enabled = false
permissions = ["cwd:read", "process:run:zoxide"]

Existing [zsh.native_plugins] and [zsh.native_widgets] config remains a legacy migration compatibility surface. New machine-managed config should use [plugins], while user-authored interactive startup should use ~/.winuxshrc. Official shell helper packs can ship reviewed bundle-local init.winux source scripts. If ~/.winuxshrc exists, it is the source-plugin entry point and loads the framework directly. Without ~/.winuxshrc, the legacy managed startup path can still load enabled source packs before fallback ~/.winshrc. Use winuxsh plugin list, winuxsh plugin search, winuxsh plugin themes, and winuxsh plugin review for current inventory, theme sources, and permission checks; legacy --zsh-native-packs remains migration-only.

What next