{"id":13529722,"url":"https://github.com/jamesob/desk","last_synced_at":"2025-05-15T04:05:38.481Z","repository":{"id":43262409,"uuid":"44887812","full_name":"jamesob/desk","owner":"jamesob","description":"A lightweight workspace manager for the shell","archived":false,"fork":false,"pushed_at":"2022-07-07T17:57:09.000Z","size":470,"stargazers_count":2548,"open_issues_count":20,"forks_count":112,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-14T06:49:54.456Z","etag":null,"topics":["bash","desk","shell","shell-script","workspace-manager","zsh"],"latest_commit_sha":null,"homepage":null,"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/jamesob.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}},"created_at":"2015-10-24T22:42:23.000Z","updated_at":"2025-04-11T05:11:28.000Z","dependencies_parsed_at":"2022-09-15T20:01:33.550Z","dependency_job_id":null,"html_url":"https://github.com/jamesob/desk","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesob%2Fdesk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesob%2Fdesk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesob%2Fdesk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesob%2Fdesk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesob","download_url":"https://codeload.github.com/jamesob/desk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270645,"owners_count":22042859,"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","desk","shell","shell-script","workspace-manager","zsh"],"created_at":"2024-08-01T07:00:38.850Z","updated_at":"2025-05-15T04:05:33.462Z","avatar_url":"https://github.com/jamesob.png","language":"Shell","readme":"\n# ◲  desk\n\n[![build](https://api.travis-ci.org/jamesob/desk.svg?branch=master)](https://travis-ci.org/jamesob/desk) [![Join the chat at https://gitter.im/jamesob/desk](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jamesob/desk?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nLightweight workspace manager for the shell.\n\nDesk makes it easy to flip back and forth between different project contexts in\nyour favorite shell. Change directory, activate a virtualenv or rvm, load\nin domain-specific aliases, environment variables, functions, arbitrary shell files, \nall in a single command.\n\nInstead of relying on `CTRL-R` to execute and recall (\"that command's gotta\nbe here somewhere...\"), desk helps shorten and document those actions with\nshell aliases and functions, which are then namespaced under a particular\ndesk.\n\nBecause Deskfiles are just enriched shell scripts, the possibilities are \nendless. For example, when doing work on AWS I have desk \nsecurely load AWS API keys into environment variables via \n[`pass`](https://www.passwordstore.org/) -- no effort on my part, and no \nrisk of accidentally persisting that sensitive information to a history file.\n\n\u003cimg src='screencap.gif' width=700\u003e\n\nI have a hard time calling this a \"workspace manager\" with a straight\nface -- it's basically just a shell script that sources another shell script in a new shell.\nBut I often find myself working in multiple different code trees simultaneously:\nthe quick context switches and namespaced commands that desk facilitates\nhave proven useful.\n\nThere are no dependencies other than `bash`. Desk is explicitly tested with `bash`,\n`zsh`, and `fish`.\n\n```sh\n◲  desk 0.6.0\n\nUsage:\n\n    desk\n        List the current desk and any associated aliases. If no desk\n        is being used, display available desks.\n    desk init\n        Initialize desk configuration.\n    desk (list|ls)\n        List all desks along with a description.\n    desk (.|go) [\u003cdesk-name-or-path\u003e [shell-args...]]\n        Activate a desk. Extra arguments are passed onto shell. If called with\n        no arguments, look for a Deskfile in the current directory. If not a\n        recognized desk, try as a path to directory containing a Deskfile.\n    desk run \u003cdesk-name\u003e \u003ccmd\u003e\n        Run a command within a desk's environment then exit. Think '$SHELL -c'.\n    desk edit [desk-name]\n        Edit (or create) a deskfile with the name specified, otherwise\n        edit the active deskfile.\n    desk help\n        Show this text.\n    desk version\n        Show version information.\n\nSince desk spawns a shell, to deactivate and \"pop\" out a desk, you\nsimply need to exit or otherwise end the current shell process.\n```\n\nFor example, given this deskfile (`~/.desk/desks/tf.sh`):\n```sh\n# tf.sh\n#\n# Description: desk for doing work on a terraform-based repository\n#\n\ncd ~/terraform-repo\n\n# Set up AWS env variables: \u003ckey id\u003e \u003csecret\u003e\nset_aws_env() {\n  export AWS_ACCESS_KEY_ID=\"$1\"\n  export AWS_SECRET_ACCESS_KEY=\"$2\"\n}\n\n# Run `terraform plan` with proper AWS var config\nplan() {\n  terraform plan -module-depth=-1 \\\n    -var \"access_key=${AWS_ACCESS_KEY_ID}\" \\\n    -var \"secret_key=${AWS_SECRET_ACCESS_KEY}\"\n}\n\n# Run `terraform apply` with proper AWS var config\nalias apply='terraform apply'\n```\n\nwe'd get\n\n```sh\n$ desk . tf\n$ desk\n\ntf\ndesk for doing work on a terraform repo\n\n  set_aws_env   Set up AWS env variables: \u003ckey id\u003e \u003csecret\u003e\n  plan          Run `terraform plan` with proper AWS var config\n  apply         Run `terraform apply` with proper AWS var config\n```\n\nBasically, desk just associates a shell script (`name.sh`) with a name. When\nyou call `desk . name`, desk drops you into a shell where `name.sh` has been\nexecuted, and then desk extracts out certain comments in `name.sh` for useful\nrendering.\n\n### Installing\n\n#### With homebrew\n\n`brew install desk`\n\n#### With curl\n\nAssuming `~/bin` exists and is on the PATH... otherwise, substitute `/usr/local/bin`\nand add `sudo` as needed.\n\n0. `curl https://raw.githubusercontent.com/jamesob/desk/master/desk \u003e ~/bin/desk`\n0. `chmod +x ~/bin/desk`\n\n#### With git\n\n0. `git clone git@github.com:jamesob/desk.git \u0026\u0026 cd desk \u0026\u0026 sudo make install`\n\nAfter that, run `desk init` and start adding deskfiles with either `desk edit [deskfile name]`\nor by manually adding shell scripts into your deskfiles directory (by default `~/.desk/desks/`).\n\n### Enabling shell extensions\n\n**NB**: Shell extensions are automatically enabled if Desk is installed via Homebrew.\n\n#### Using bash\n\n0. Add `source /path/to/desk/repo/shell_plugins/bash/desk` to your `.bashrc`.\n\n#### Using fish\n\n```fish\nmkdir -p ~/.config/fish/completions\ncp /path/to/desk/repo/shell_plugins/fish/desk.fish ~/.config/fish/completions\n```\n\n#### Using zsh\n\n0. Add `fpath=(/path/to/desk/repo/shell_plugins/zsh $fpath)` to your `.zshrc`.\n\n\nOptionally, use one of the zsh plugin frameworks mentioned below.\n\n#### Using [oh-my-zsh](http://ohmyz.sh/)\n\n0. `make oh-my-zsh` from within this repo. This sets up a symlink.\n\nor\n\n0. `cd ~/.oh-my-zsh/custom/plugins`\n0. `git clone git@github.com:jamesob/desk.git /tmp/desk \u0026\u0026 cp -r /tmp/desk/shell_plugins/zsh desk`\n0. Add desk to your plugin list\n\n#### Using [Antigen](https://github.com/zsh-users/antigen)\n\n0. Add `antigen bundle jamesob/desk shell_plugins/zsh` to your `.zshrc`\n0. Open a new terminal window. Antigen will clone the desk repo and add it to your path.\n\n#### Using [zgen](https://github.com/tarjoilija/zgen)\n\n0. Add `zgen load jamesob/desk shell_plugins/zsh` to your `.zshrc` with your other load commands\n0. `rm ~/.zgen/init.zsh`\n0. Start a new shell; zgen will generate a new `init.zsh` and automatically clone the desk repository for you and add it to your path.\n\n### Deskfile rules\n\nDeskfiles are just shell scripts, nothing more, that live in the desk config directory.\nDesk does pay attention to certain kinds of comments, though.\n\n- *description*: you can describe a deskfile by including `# Description: ...`\n  somewhere in the file.\n\n- *alias and function docs*: if the line above an alias or function is a\n  comment, it will be used as documentation.\n \n### Deskfiles\n\nDeskfiles are just shell scripts at the root of a project directory that \nadhere to the conventions above. These can be put into version control to\nformalize and ease common development tasks like running tests or doing\nlocal builds.\n\nFor example, if we have some directory or repository called `myproject`, if\nwe create `myproject/Deskfile`, we'll be able to do any of the following:\n```sh\n$ desk go /path/to/myproject/\n$ desk go /path/to/myproject/Deskfile\nmyproject/ $ desk go .\nmyproject/ $ desk go\n```\n \n### Sharing deskfiles across computers\n\nOf course, the desk config directory (by default `~/.desks`) can be a symlink\nso that deskfiles can be stored in some centralized place, like Dropbox,\nand so shared across many computers.\n\n### Using a non-default config location\n\nBy default, desk configuration lives in `~/.desk` (`$DESK_DIR`) and deskfiles\nlive in `~/.desk/desks` (`$DESK_DESKS_DIR`). If you want to use some other\nlocation, specify as much in `desk init` and then ensure you set `$DESK_DIR`\nand/or `$DESK_DESKS_DIR` to match in your shell's rc file.\n\n### Shortening invocation\n\nTyping `desk .` frequently can get old; personally, I like to alias this with\n```sh\nalias d.='desk .'\n```\nin my shell rc file.\n\n### Usage with OS X\n\nDesk won't work when used strictly with `~/.bash_profile` on OS X's terminal, since\nthe content of `~/.bash_profile` is only executed on *login*, not shell creation, as\nexplained [here](http://www.joshstaiger.org/archives/2005/07/bash_profile_vs.html).\n\nMy recommendation is to use `~/.bashrc` as your general-purpose config file, then simply\nhave `~/.bash_profile` point to it:\n```sh\n# ~/.bash_profile\n\nif [ -f ~/.bashrc ]; then\n   source ~/.bashrc\nfi\n```\n\n### Related projects\n\n- [godesk](https://github.com/hamin/godesk) by @hamin: a desk launcher with fuzzy filtering\n\n\n### Tips accepted\n\n![18ehgMUJBqKc2Eyi6WHiMwHFwA8kobYEhy](http://i.imgur.com/KAfUPA6.png)\n\nBTC: `18ehgMUJBqKc2Eyi6WHiMwHFwA8kobYEhy`\n\nHalf of all tips will be donated to [an organization providing aid to Syrian refugees](http://www.moas.eu/).\n\n#### Donations made on behalf of tippers\n\n| date | amount | organization |\n| ---- | ------ | ------------ |\n| 2015-11-18 | $1.07 | http://moas.eu |\n| 2016-11-14 | $21.00 | http://moas.eu |\n","funding_links":[],"categories":["Command-Line Productivity","Shell","Tools","\\*nix/\\*nux"],"sub_categories":["Bash","Terminal"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesob%2Fdesk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesob%2Fdesk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesob%2Fdesk/lists"}