{"id":13683152,"url":"https://github.com/axonasif/dotsh","last_synced_at":"2025-03-18T14:30:43.816Z","repository":{"id":43350831,"uuid":"405670698","full_name":"axonasif/dotsh","owner":"axonasif","description":"A fast dotfiles and system configuration installer framework optimized for Gitpod and power users","archived":false,"fork":false,"pushed_at":"2023-10-10T20:43:33.000Z","size":86,"stargazers_count":32,"open_issues_count":2,"forks_count":22,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-16T21:01:44.937Z","etag":null,"topics":["bash","bashbox","dotfiles","dotsh","fish","gitpod","gitpod-dotfiles","linux","macos","neovim","shell","ssh","tmux","vscode","zsh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axonasif.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-12T14:54:57.000Z","updated_at":"2025-02-20T22:23:52.000Z","dependencies_parsed_at":"2024-01-14T16:10:18.167Z","dependency_job_id":"a5eedb6b-84c0-4724-9f8d-a1609fbda8ff","html_url":"https://github.com/axonasif/dotsh","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonasif%2Fdotsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonasif%2Fdotsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonasif%2Fdotsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonasif%2Fdotsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axonasif","download_url":"https://codeload.github.com/axonasif/dotsh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244240004,"owners_count":20421380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bashbox","dotfiles","dotsh","fish","gitpod","gitpod-dotfiles","linux","macos","neovim","shell","ssh","tmux","vscode","zsh"],"created_at":"2024-08-02T13:02:02.091Z","updated_at":"2025-03-18T14:30:43.535Z","avatar_url":"https://github.com/axonasif.png","language":"Shell","readme":"# Introduction\n\nA fast dotfiles and system-configuration installer optimized for Gitpod (can be used locally too). Is this another dotfiles-manager? Nope. In fact, it will try to detect your dotfiles-manager and install your raw files through it if you're using one. This is essentially a script, it is meant to be modularly customized from source code and compiled for convenience. You can even call it a \"framework\" if you like 🙃\n\n# Quickstart for Gitpod\n\nNote: You will be using your existing dotfiles repo, `dotsh` is only the installer.\n\nOpen this repo on Gitpod:\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#github.com/axonasif/dotsh)\n\nThen run `dotsh config` on a terminal for interactive configuration wizard.\n\nOr if you just want to try it out:\n\n- Put https://github.com/axonasif/dotsh on your **[Gitpod Preferences](https://gitpod.io/preferences) \u003e Dotfiles**\n- Later, you could customize it by running `dotsh config` if you want.\n\nLearn more about dotfiles behaviour on Gitpod at https://www.gitpod.io/docs/config-dotfiles\n\n# Quickstart for local machine\n\n\u003cdetails\u003e\n  \u003csummary\u003eExpand\u003c/summary\u003e\n\nRight now **only Linux and MacOS is supported**. In theory it could work on other \\*nix systems and maybe Windows, that said, the script could run fine but some special handling of how things are installed or configured needs to be done for other systems, please contribute if you're an user of an \"unsupported\" system.\n\n### Prerequisites\n\n- git\n- bash 4.3 or above\n\n### Linux\n\nInstall `git` with your distro's package manager. Generally `bash` version is not an issue on Linux distros.\n\n### MacOS\n\nIn MacOS you could install these via `brew` before proceeding.\n\n```bash\n# If you don't have homebrew already, otherwise skip this command\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\nbash -lic 'set -m; brew install git bash'\n\nexec bash -li # Reload bash\n```\n\nAfter you've made sure that the prerequisites are met, run:\n\n```bash\n# You may use your own fork instead\ngit clone https://github.com/axonasif/dotsh ~/.dotfiles\nbash ~/.dotfiles/install.sh\n```\n\n\u003c/details\u003e\n\n# Features\n\nMost of these features stemmed from my personal needs. Another reason was to avoid repetitive work while answering some frequent questions at the Gitpod Discord server that required manual handcrafting for each scenario, an unified ~~solution~~ workaround was needed. I simply couldn't wait but try implementing them myself as long it's possible within the context of `dotfiles` layer on Gitpod. I really like how programmable Gitpod can be unlike anything out there! (although I wish it was more obvious).\n\n## Fast installation\n\nhttps://user-images.githubusercontent.com/39482679/208247012-9341dc34-f191-46d8-85e1-ee3a937e8f79.mp4\n\nThe installation is highly parallelized. This leads to a reasonably fast Gitpod workspace startup. In the regular way it'd take at least 60seconds for my dotfiles installation itself, rendering dotfiles unusable. Some tricks are used to start fast without crashing things that rely on your custom-shell and tmux (for example) while they're being installed/configured in the background. One of the most important trick is lazy-loading binaries with (optional) locking.\n\n\u003cdetails\u003e\n  \u003csummary\u003eExtra details\u003c/summary\u003e\n\n### Lazy loading of binaries\n\nA `bash` script is placed at an alternate place in `$PATH` or even the exact path of the real binary (where suitable) as a \"shim\". External programs (outside of `dotsh` process) will hit the \"shim\" and the \"shim\" will sleep until it receives a signal from `dotsh` (when necessary, otherwise no signals are required). This prevents the crash of programs that depends on a particular program. So for most of the cases, such dependant programs can get ahead of time with their tasks and only wait when necessary.\n\nThis is quite complicated under the hood due to race-conditions and filesystem operations, thankfully it didn't involve something like a fusefs implementaion which has it's own requirements (although that probably would've been easier to debug).\n\nMore details at [here](/docs/REFERENCE.md#awaitcreate_shim-unstable)\n\n\u003c/details\u003e\n\nOfficial issue: https://github.com/gitpod-io/gitpod/issues/7592\n\n## Live testing of dotfiles and `.gitpod.yml`\n\nhttps://user-images.githubusercontent.com/39482679/204037025-7747cf73-3204-43bc-a8a7-633c603861ad.mp4\n\nTesting out `dotfiles` or `.gitpod.yml` changes can be a lengthy and difficult process (_something I have to do pretty much everyday_). This live testing capability allowed me to quickly prototype the rest of `dotsh` logic, which would've been quite impossible otherwise.\n\n\u003cdetails\u003e\n  \u003csummary\u003eUsage and details\u003c/summary\u003e\n\n### For only testing dotfiles changes:\n\n**If you opened your `dotsh` repo on Gitpod**:\n\n\u003e Assuming your [CWD](https://en.wikipedia.org/wiki/Working_directory) is `/workspace/dotsh`, you can run `bashbox livetest`\n\n**If you didn't open `dotsh` but a different repo and want to test your dotfiles**:\n\n\u003e - Go to `~/.dotfiles` (where `dotsh` gets cloned by Gitpod) by running `cd ~/.dotfiles`\n\u003e - Now run `bashbox livetest`\n\u003e Tip: You could also do `bashbox -C ~/.dotfiles livetest` if you do not want to `cd ~/.dotfiles`.\n\n### For testing `.gitpod.yml` changes of a workspace (including dotfiles):\n\n- Run `dotsh livetest` from anywhere in your workspace.\n\n### Extra details\n\n`livetest` command comes from [Bashbox.sh](./Bashbox.sh) as a package function. `dotsh livetest` command is an alias to `bashbox -C \u003cdotfiles-dir\u003e livetest ws`.\n\nIt shares almost everything from the host Gitpod workspace to the testing container, it may include:\n\n- `/ide` (mirror, doesn't affect the original one)\n- `/workspace` (ephemeral mirror, CoW via overlayfs)\n- `/.supervisor` (direct bind mount)\n- `/usr/bin/gp` (read-only)\n- `/dev/fuse` (for things like `rclone mount`)\n- `/var/run/docker.sock` (for using docker inside the testing container)\n- dotfiles (mirror)\n- Local network (to communicate with the IDE process, Gitpod API and expose ports to HOST)\n\nThis speeds up the process since we're just re-using the resources and is not expensive.\n\n\u003c/details\u003e\n\n[Tmux integration](#tmux-integration) and the overall [quick feedback](#fast-installation) makes it much more useful.\n\n**Note:** This is only optimized for Gitpod and will not work elsewhere. You can also try [run-gp](https://github.com/gitpod-io/run-gp) which also supports running a Gitpod workspace locally.\n\nOfficial issue: https://github.com/gitpod-io/gitpod/issues/7671.\n\n## Tmux integration\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://user-images.githubusercontent.com/39482679/203600977-327824cb-26a9-4802-821d-004363922f5b.png\" alt=\"gitpod.tmux\"\u003e\u003c/p\u003e\n\nUsing SSH or terminal in general without TMUX feels powerless! Gitpod got amazing SSH support and various different ways to SSH into its workspaces.\n\n[gitpod.tmux](https://github.com/axonasif/gitpod.tmux) plugin is auto-installed for you, and Gitpod tasks are opened inside tmux via `dotsh`.\n\n`dotsh` pervents Gitpod tasks to be executed in the regular `bash` terminals and spawns them inside `tmux` windows. After the task completion in a POSIX friendly shell, it'll auto switch to your favorite shell.\n\n### Integrated tmux usage from VSCode\n\nVSCode is a great editor when you want to code from the browser, having an integrated tmux experience was must for me! All your new vscode terminals will get opened as tmux windows instead.\n\nhttps://user-images.githubusercontent.com/39482679/204037099-854db4a9-430b-470f-9444-f3d1738446f8.mp4\n\n## Cross-workspace and local filesync\n\nFile sync is a crutial feature when working with ephemeral workspaces. This let's you sync files across workspaces or locally to individual workspaces. That means you could persist your login for CLI programs, cache big files and so on. It's gluing together [rclone](https://github.com/rclone/rclone) to accomplish this, nothing special on it's own.\n\nThis is easily one of the most wanted features on Gitpod. See [/docs/PERSISTING_AUTH.md](/docs/PERSISTING_AUTH.md) for examples of a few use-cases.\n\n\u003cdetails\u003e\n  \u003csummary\u003eUsage\u003c/summary\u003e\n\n\u003e Run `dotsh config rclone` for initial setup of `rclone` (if you haven't yet).\n\nTo start syncing files, you can use:\n\n```bash\n# This will save and restore in the absolute static path.\ndotsh filesync save /path/to/file another_file\n```\n\nTo save a file from your `$HOME` directory and to dynamically auto restore it based on user home dir:\n\n```bash\n# Useful when you're using dotsh both locally and on Gitpod.\n# -dh is short form of --dynamic-home argument.\n# I'm saving docker.json to persist my login, so that I don't have to login every time.\ncd $HOME\ndotsh filesync -dh .config/docker.json\n```\n\n### Why use `rclone`?\n\n- It's cross-platform.\n- Very powerful tool, has tons of options.\n- You own your data and have the flexibility to decide where to host it.\n\n\u003c/details\u003e\n\nOfficial issue: https://github.com/gitpod-io/gitpod/issues/9284\n\n## Optimized for CLI EDITOR(s)\n\nYour favorite CLI editor is quickly auto installed for you. Also several common CLI tools, dependencies, editor plugins/presets are install and configured based on your preference in ahead of time. So you can easily get started with your own editor-config without worrying about tweaking the system.\n\nThe following editors are supported:\n\n- Emacs\n- Helix\n- NeoVim (I use this one)\n- Vim\n\nA popular editor-preset (e.g. LunarVim [awesome config BTW!], Spacemacs) is installed unless your own config is detected. You can customize this from [./src/variables.sh](./src/variables.sh#L81).\n\nOfficial issue: https://github.com/gitpod-io/gitpod/issues/9323\n\n## Optimized for custom SHELL(s)\n\nYou can use you favorite shell on Gitpod task-terminals while perseving bash/posix compatibility with the Gitpod task scripts and also the shell-environment. You don't have to sacrifice the usability of custom shells!\n\n\u003cdetails\u003e\n  \u003csummary\u003eDetails\u003c/summary\u003e\n\nThere is an _universal_ issue with shells like `fish` or `zsh`, most tools (e.g. cargo) provide shell-environment scripts that are POSIX or bash-compatible and usually installed for the system login-shell. I personally use `fish`, had to make a bit of efforts for dailydriving it everywhere as the interactive shell. In a local PC, what usually happens is that `fish` or `zsh` inherits the environment variables from the GUI terminal-emulator process, which are stemmed from the system zygote process spawning other (*GUI) applications on top of the login shell. This is also why you'd be asked to re-login (display-manager) or reboot after changing your shell from `chsh` on a traditional *unix system to reflect the changes.\n\n### Fish\n\nIt will install [fisher](https://github.com/jorgebucaran/fisher) and install the following plugins via it:\n\n- [axonasif/bashenv.fish](https://github.com/axonasif/bashenv.fish) (to use the env customizations of Gitpod and other tools from `bash`)\n- [PatrickF1/fzf.fish](https://github.com/PatrickF1/fzf.fish) (for a powerful fzf integration)\n\nYou can modify this [here](/blob/ac7f1a9f00383d9cee8452bb32de7504b904dd31/src/variables.sh#L35).\n\n### Zsh\n\nThe following are auto-installed:\n\n- [axonasif/bashenv.zsh](https://github.com/axonasif/bashenv.zsh) (to use the env customizations of Gitpod and other tools from `bash`)\n- [ohmyzsh](https://github.com/ohmyzsh/ohmyzsh).\n\n\u003c/details\u003e\n\nOfficial issue: https://github.com/gitpod-io/gitpod/issues/10105\n\n## Easy SHH'ing through local terminal\n\nhttps://user-images.githubusercontent.com/39482679/204090871-7abfb4b0-d757-40cb-ab0f-52f0ba5ccbd0.mp4\n\nLaunch gitpod workspaces automatically inside a [local terminal emulator via `ssh://`](/docs/REFERENCE.md#open-ssh-protocol-urls-in-local-terminal-emulator) without having to copy-paste manually!\n\nOfficial issue: https://github.com/gitpod-io/gitpod/issues/9323\n\n## Easy cross-platform package installation\n\nWe need not to worry about package management and leave it on the shoulders of `nix`, which is a very powerful package manager, unlike any other! Oh and, it's cross-platform too with tons of packages. Since Gitpod workspaces are ephemeral, using `nix` is even easier!\n\nWith `dotsh`, `nix` package installations are chunked into different levels to optimize terminal readiness. To add your own packages, edit the `PACKAGES` section on [./src/variables.sh](./src/variables.sh#L81)\n\nFor example, here's how the level one packages array looks like on [./src/variables.sh](./src/variables.sh#L81):\n\n\n```bash\ndeclare nixpkgs_level_1+=(\n    nixpkgs.ripgrep\n    nixpkgs.fd\n    nixpkgs.fzf\n)\n```\n\nYou can find packages at https://search.nixos.org/packages\n\n## Host aware multi-layer dotfiles installation\n\nIt will not overwrite some crutial host files (e.g. `.bashrc`, `.gitconfig` and etc.) while installing your `dotfiles` repos but virtually load your ones to preserve integrity of the host system. (if you're using a custom dotfiles-manager like chezmoi, you need to handle it through your dotfiles-manager)\n\nFor more details on this and an example raw dotfiles tree, check [this](https://github.com/axonasif/dotfiles)\n\nBy default, it will use a basic symlinking mechanism unless you're using a dotfiles-manager, currently the following is recognized:\n\n- chezmoi\n\n## Extra goodies\n\n- Auto login into `gh` or `glab` CLI based on your repository context.\n- Shell completion for `gp` CLI.\n\n# Contributing and development\n\nOpen this repo on Gitpod:\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#github.com/axonasif/dotsh)\n\nAnd use the [livetesting](#live-testing-of-dotfiles-and-gitpodyml) mechanism for testing out your changes.\n\nYou can also run `bashbox build --release` for only compiling.\n\nFor viewing logs from the filesystem: `less -FXR ~/.dotfiles.log`\n\nAlso check [docs/REFERENCE.md](/docs/REFERENCE.md)\n\n# Back story\n\n`dotsh` is basically a *pretty* accumulation of some of my scattered scripts that I had before, now it's just a bit more organized and meaningful. And also the fact that the Gitpod community bought me encouragement for putting this together. I didn't have a proper dotfiles setup before, it was a mess but it's also true that I've been iterating over my dotfiles for the last ~9 months 😝. If you found it useful, let me know! (you can find me hanging around at the [Gitpod Discord server](https://gitpod.io/chat))\n\nI also personally hope that many of the things that I had to implement though Dotfiles would have an official and more robust implementation on Gitpod in the future! (Please react \"👍\" on the linked official issues BTW, that might help those getting prioritized)\n\nThis project was built with [bashbox](https://github.com/bashbox/bashbox), and it's following libraries:\n\n- [std](https://github.com/bashbox/std)\n- [libtmux](https://github.com/bashbox/libtmux)\n\nGenerally, bash scripts are error prone, hard to debug and maintain. But it changes with bashbox!\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonasif%2Fdotsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxonasif%2Fdotsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonasif%2Fdotsh/lists"}