init

Rootless-first bootstrap for bioinformatics and computational biology work on macOS and Linux. It uses mise to install tools in your user account, configure Zsh, and prepare a small Conda base. It does not ask for sudo and does not edit system files.

Language	Jump to
English	English
简体中文	简体中文

The normal source is the official repository: https://github.com/fantasticjoe/init.git. Help for slow or blocked GitHub connections is in Mainland-China network help.

English

1. Before you start

You need:

macOS or Linux
curl and git
On Linux, zsh and trusted CA certificates
A normal user account; this project does not use sudo

Open a terminal. You can stop after the check in step 5 if you only want the standard installation.

2. Install mise

Run the official installer, then make the new command available in this terminal:

curl --proto '=https' --tlsv1.2 -fsSL https://mise.run | sh
export PATH="$HOME/.local/bin:$PATH"
mise --version

If mise --version prints a version, continue. If your shell still cannot find mise, use ~/.local/bin/mise in the commands below.

3. Preview the changes

--dry-run only shows what would change. It does not install anything:

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --dry-run

Read the output. Pay special attention to the proposed ~/.zshrc symlink and the user directories that will be created.

4. Apply the changes

When the preview looks right, run the same command without --dry-run:

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git

The first run may ask you to confirm. In a non-interactive job, add --yes only after you have reviewed a successful dry run:

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --yes

Open a new Zsh window after installation so that the managed shell settings are loaded.

5. Check that it worked

Run the project diagnostic task:

mise run doctor

It checks mise, Zsh, Git, curl, the Oh My Zsh repositories, the managed ~/.zshrc link, and the Miniforge/Conda setting. You can also inspect the current tools with:

mise ls --current
~/miniforge3/bin/conda info

6. What it changes

The bootstrap manages these user-owned paths:

~/.oh-my-zsh and three Zsh plugins
~/.zshrc as a symlink to dotfiles/zshrc
Node.js LTS, stable Rust, Go, uv, jq, yq, ripgrep, fd, fzf, and bat through mise
Miniforge at ~/miniforge3, with Conda base auto-activation disabled
The diagnostic task mise run doctor

It does not change your login shell, edit /etc/shells, install Docker, or modify other system files. On Linux, missing zsh, git, curl, or CA certificates are reported for an administrator to install.

7. If you already have `~/.zshrc`

Bootstrap will not overwrite a regular file or an unrelated symlink. Back it up to a path that does not exist, then run bootstrap again:

backup="$HOME/.zshrc.before-init"
test ! -e "$backup" || { echo "choose another backup path" >&2; exit 1; }
mv "$HOME/.zshrc" "$backup"
mise bootstrap \
  --from https://github.com/fantasticjoe/init.git

Only use --force-dotfiles when you have checked the existing link and really want the repository to replace it:

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --force-dotfiles

To undo this choice, remove the managed link and move your backup back to ~/.zshrc manually.

8. Use Conda after installation

The managed Zsh file loads Conda but leaves the base environment off. Start a new terminal and activate an environment only when you need it:

conda env list
conda create -n bio python=3.12
conda activate bio
conda deactivate

Use mise and uv for ordinary Python utilities. Keep Scanpy, scvi-tools, PyTorch/CUDA, Snakemake, Bioconda-heavy stacks, and project scientific environments in Conda.

9. Update or use a local checkout

To refresh this repository and clean managed checkouts:

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --update

Updates refuse to reset dirty Git repositories. Commit or preserve local changes first, and use --dry-run when you are unsure.

For review, an offline hand-off, or an approved internal mirror, use a local checkout:

mkdir -p "$HOME/src"
git clone https://github.com/fantasticjoe/init.git "$HOME/src/init"
cd "$HOME/src/init"
mise trust
mise bootstrap --from "$PWD" --dry-run
mise bootstrap --from "$PWD"

The checkout is only the bootstrap source. Oh My Zsh and its plugins still need to be reachable, or already present as valid Git checkouts.

10. Mainland-China network help

Use the official GitHub and mise.run URLs whenever they work. If they are slow or blocked, try these options in order:

Use an institutional HTTP(S) proxy, artifact cache, or approved internal Git mirror. Keep the commands above unchanged when the proxy handles the network.
Prepare the local checkout on a network that can reach GitHub, copy it to the target machine, and run mise bootstrap --from /path/to/init.
Use a public GitHub proxy only as a last resort. Check its current documentation and trust its operator first. Services such as ghfast.top and gh-proxy.com can be unavailable or change their URL format; they are not official project sources.

If a provider explicitly documents prefixing a complete GitHub URL, the pattern looks like this. Replace the placeholder, inspect the downloaded script, and do not pipe an unfamiliar mirror response directly into bash:

MIRROR_PREFIX='https://<approved-provider-prefix>/'

git clone "${MIRROR_PREFIX}https://github.com/fantasticjoe/init.git" \
  "$HOME/src/init"
cd "$HOME/src/init"
mise trust
mise bootstrap --from "$PWD" --dry-run
mise bootstrap --from "$PWD"

The same provider may document a way to fetch mise.run. If it does not, use an institutional HTTPS_PROXY or an approved package/cache for installing mise. The bootstrap still downloads the GitHub repositories listed in mise.toml; do not silently replace those URLs with unknown sources.

Optional: TUNA Miniforge mirror

If GitHub is reachable only through an approved Miniforge mirror, install that one component first. Choose the asset for your machine, inspect the installer, and use the same prefix (~/miniforge3) that bootstrap expects:

asset=Miniforge3-MacOSX-arm64.sh
tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/miniforge3.XXXXXX")"
curl -fL \
  "https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniforge/$asset" \
  -o "$tmp_dir/$asset"
sed -n '1,80p' "$tmp_dir/$asset"
bash "$tmp_dir/$asset" -b -p "$HOME/miniforge3"
"$HOME/miniforge3/bin/conda" config --set auto_activate_base false
rm -f "$tmp_dir/$asset"
rmdir "$tmp_dir" 2>/dev/null || true

Use Miniforge3-Linux-x86_64.sh, Miniforge3-Linux-aarch64.sh, or Miniforge3-MacOSX-x86_64.sh on other supported architectures. Compare the checksum with the corresponding official release when one is published.

11. Troubleshooting

Symptom	What to do
`mise: command not found`	Run `export PATH="$HOME/.local/bin:$PATH"`, or use `~/.local/bin/mise`.
Bootstrap refuses `~/.zshrc`	Back up the existing path as shown in step 7; do not delete it blindly.
Linux prerequisite is missing	Ask the administrator to install `zsh`, `git`, `curl`, and CA certificates, then rerun bootstrap.
`~/miniforge3` is incomplete	Move it to a new backup name, then rerun bootstrap.
GitHub cannot be reached	Use an approved proxy/cache or the local-checkout method in step 10.

For a full state report, run:

mise doctor
mise run doctor

12. Compatibility wrapper and limits

The legacy init.sh remains as a small wrapper. It installs mise when needed and forwards arguments to mise bootstrap; it does not install system packages or edit shell files by itself:

curl -fsSL https://raw.githubusercontent.com/fantasticjoe/init/main/init.sh \
  -o "$HOME/init.sh"
sed -n '1,220p' "$HOME/init.sh"
bash "$HOME/init.sh" --dry-run

Supported hosts are Intel/Apple Silicon macOS and x86_64/aarch64 Linux. Rootless Podman may suit workstations and servers; HPC sites often provide Apptainer or Singularity. Follow local policy for containers and for home directories on NFS, Lustre, or GPFS.

13. License

MIT. See LICENSE.

简体中文

1. 开始前准备

你需要：

macOS 或 Linux
curl 和 git
Linux 还需要 zsh 和受信任的 CA 证书
普通用户账号；本项目不会使用 sudo

打开终端即可。只想完成标准安装时，做到第 5 步的检查就够了。

2. 安装 mise

先安装官方 mise，再把它加入当前终端的 PATH：

curl --proto '=https' --tlsv1.2 -fsSL https://mise.run | sh
export PATH="$HOME/.local/bin:$PATH"
mise --version

如果能看到版本号，就可以继续。如果终端仍提示找不到 mise，把下面命令中所有 mise 换成 ~/.local/bin/mise。

3. 先预览，不会修改文件

--dry-run 只显示计划，不会安装任何东西：

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --dry-run

请先看输出，尤其注意 ~/.zshrc 将变成符号链接，以及哪些用户目录会被创建。

4. 正式安装

确认预览内容没问题后，去掉 --dry-run 再运行一次：

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git

第一次运行可能会要求确认。非交互环境只有在确认 dry-run 输出后，才添加 --yes：

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --yes

安装完成后，请重新打开一个 Zsh 终端，让新的配置生效。

5. 检查是否成功

运行项目自带的检查任务：

mise run doctor

它会检查 mise、Zsh、Git、curl、Oh My Zsh 仓库、受管的 ~/.zshrc 链接，以及 Miniforge/Conda 设置。还可以查看工具和 Conda 状态：

mise ls --current
~/miniforge3/bin/conda info

6. 它会改什么

安装只管理用户目录中的内容：

~/.oh-my-zsh 和三个 Zsh 插件
让 ~/.zshrc 链接到本仓库的 dotfiles/zshrc
通过 mise 安装 Node.js LTS、稳定版 Rust、Go、uv、jq、yq、ripgrep、fd、fzf、bat
把 Miniforge 安装到 ~/miniforge3，并关闭 Conda base 自动激活
提供 mise run doctor 检查任务

它不会修改登录 shell、/etc/shells，不会安装 Docker，也不会修改其他系统文件。 Linux 缺少 zsh、git、curl 或 CA 证书时，只会提示管理员处理。

7. 已经有 `.zshrc` 怎么办

如果 ~/.zshrc 是普通文件或无关的符号链接，bootstrap 会拒绝覆盖。请先备份到一个不存在的新路径，再重新运行：

backup="$HOME/.zshrc.before-init"
test ! -e "$backup" || { echo "请选择新的备份路径" >&2; exit 1; }
mv "$HOME/.zshrc" "$backup"
mise bootstrap \
  --from https://github.com/fantasticjoe/init.git

只有在确认确实要替换现有链接时，才使用 --force-dotfiles：

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --force-dotfiles

以后不想使用受管配置时，请手动删除链接，再把备份移回 ~/.zshrc。不要直接删除还没检查过的用户配置。

8. 安装后如何使用 Conda

受管的 Zsh 配置会加载 Conda，但默认不打开 base 环境。重新打开终端后，需要时再手动激活：

conda env list
conda create -n bio python=3.12
conda activate bio
conda deactivate

普通 Python 工具使用 mise 和 uv。Scanpy、scvi-tools、PyTorch/CUDA、Snakemake、重度依赖 Bioconda 的软件栈，以及项目科学环境，建议放在 Conda 环境中。

9. 更新或使用本地 checkout

想更新本仓库和受管的干净 checkout 时运行：

mise bootstrap \
  --from https://github.com/fantasticjoe/init.git \
  --update

更新不会重置有改动的 Git 仓库。请先提交或保存本地改动；不确定时先加 --dry-run 预览。

审阅代码、准备离线安装，或使用已批准的内部镜像时，可以先 clone 到本地：

mkdir -p "$HOME/src"
git clone https://github.com/fantasticjoe/init.git "$HOME/src/init"
cd "$HOME/src/init"
mise trust
mise bootstrap --from "$PWD" --dry-run
mise bootstrap --from "$PWD"

本地 checkout 只解决 bootstrap 源码的位置；Oh My Zsh 和插件仓库仍需可访问，或已经作为有效 Git checkout 放在目标位置。

10. 中国大陆网络帮助

能访问时，优先使用官方 GitHub 和 mise.run 地址。访问慢或失败时，按以下顺序尝试：

使用机构 HTTP(S) 代理、制品缓存或已经批准的内部 Git 镜像。代理能处理网络时， README 前面的命令不需要改。
在能访问 GitHub 的网络环境先准备本地 checkout，再复制到目标机器，运行 mise bootstrap --from /path/to/init。
公共 GitHub 代理只作为最后手段。使用前查看当前文档并确认信任运营方。 ghfast.top、gh-proxy.com 等服务可能失效或改变 URL 格式，不是本项目的官方源。

只有服务商明确说明“可以给完整 GitHub URL 加前缀”时，才使用下面的形式。请替换占位符，先检查内容，不要把陌生镜像的响应直接通过管道交给 bash：

MIRROR_PREFIX='https://<approved-provider-prefix>/'

git clone "${MIRROR_PREFIX}https://github.com/fantasticjoe/init.git" \
  "$HOME/src/init"
cd "$HOME/src/init"
mise trust
mise bootstrap --from "$PWD" --dry-run
mise bootstrap --from "$PWD"

如果服务商也明确支持代理 mise.run，可以按它的文档安装 mise；否则使用机构的 HTTPS_PROXY，或从已批准的缓存/软件包安装。mise.toml 中的 Oh My Zsh 和插件仍然来自 GitHub；代理无法提供时，请使用本地 checkout 或机构缓存，不要混入未知来源。

可选：使用清华 TUNA Miniforge 镜像

如果只是 Miniforge 下载慢，可以单独使用 TUNA 镜像。根据机器选择安装包，先检查脚本，并安装到 bootstrap 约定的 ~/miniforge3：

asset=Miniforge3-MacOSX-arm64.sh
tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/miniforge3.XXXXXX")"
curl -fL \
  "https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniforge/$asset" \
  -o "$tmp_dir/$asset"
sed -n '1,80p' "$tmp_dir/$asset"
bash "$tmp_dir/$asset" -b -p "$HOME/miniforge3"
"$HOME/miniforge3/bin/conda" config --set auto_activate_base false
rm -f "$tmp_dir/$asset"
rmdir "$tmp_dir" 2>/dev/null || true

其他架构请使用 Miniforge3-Linux-x86_64.sh、Miniforge3-Linux-aarch64.sh 或 Miniforge3-MacOSX-x86_64.sh。官方发布提供校验值时，请进行比对。镜像脚本在检查前都应视为不可信，绝不要直接 curl ... | bash。

11. 常见问题

现象	处理方法
`mise: command not found`	执行 `export PATH="$HOME/.local/bin:$PATH"`，或直接使用 `~/.local/bin/mise`。
bootstrap 拒绝处理 `~/.zshrc`	按第 7 步先备份，不要直接删除。
Linux 缺少前置包	请管理员安装 `zsh`、`git`、`curl` 和 CA 证书，再重新运行。
`~/miniforge3` 不完整	改名保留后重新运行 bootstrap。
GitHub 无法访问	使用批准的代理/缓存，或按第 10 步使用本地 checkout。

完整检查可以运行：

mise doctor
mise run doctor

12. 兼容入口与边界

旧版 init.sh 仍然保留为兼容入口。它只负责在需要时安装 mise，再把参数转交给 mise bootstrap；不会自行安装系统包或修改 shell 文件：

curl -fsSL https://raw.githubusercontent.com/fantasticjoe/init/main/init.sh \
  -o "$HOME/init.sh"
sed -n '1,220p' "$HOME/init.sh"
bash "$HOME/init.sh" --dry-run

支持 Intel/Apple Silicon macOS，以及 x86_64/aarch64 Linux。工作站或服务器可以考虑 Rootless Podman；HPC 通常由站点提供 Apptainer 或 Singularity。容器、NFS、Lustre、 GPFS 和作业调度都要遵循所在机构的规定。

13. 许可证

MIT，见 LICENSE。

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.claude		.claude
.codex		.codex
.cursor		.cursor
.trellis		.trellis
dotfiles		dotfiles
scripts		scripts
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
init.sh		init.sh
mise.toml		mise.toml

Navigation Menu

Repository navigation

About

Repository files navigation

init

English

1. Before you start

2. Install mise

3. Preview the changes

4. Apply the changes

5. Check that it worked

6. What it changes

7. If you already have `~/.zshrc`

8. Use Conda after installation

9. Update or use a local checkout

10. Mainland-China network help

Optional: TUNA Miniforge mirror

11. Troubleshooting

12. Compatibility wrapper and limits

13. License

简体中文

1. 开始前准备

2. 安装 mise

3. 先预览，不会修改文件

4. 正式安装

5. 检查是否成功

6. 它会改什么

7. 已经有 `.zshrc` 怎么办

8. 安装后如何使用 Conda

9. 更新或使用本地 checkout

10. 中国大陆网络帮助

可选：使用清华 TUNA Miniforge 镜像

11. 常见问题

12. 兼容入口与边界

13. 许可证

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

init

English

1. Before you start

2. Install mise

3. Preview the changes

4. Apply the changes

5. Check that it worked

6. What it changes

7. If you already have ~/.zshrc

8. Use Conda after installation

9. Update or use a local checkout

10. Mainland-China network help

Optional: TUNA Miniforge mirror

11. Troubleshooting

12. Compatibility wrapper and limits

13. License

简体中文

1. 开始前准备

2. 安装 mise

3. 先预览，不会修改文件

4. 正式安装

5. 检查是否成功

6. 它会改什么

7. 已经有 .zshrc 怎么办

8. 安装后如何使用 Conda

9. 更新或使用本地 checkout

10. 中国大陆网络帮助

可选：使用清华 TUNA Miniforge 镜像

11. 常见问题

12. 兼容入口与边界

13. 许可证

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

7. If you already have `~/.zshrc`

7. 已经有 `.zshrc` 怎么办