{"id":31074479,"url":"https://github.com/sebastiancarlos/work-notes","last_synced_at":"2026-03-09T06:32:30.382Z","repository":{"id":310586392,"uuid":"1040438096","full_name":"sebastiancarlos/work-notes","owner":"sebastiancarlos","description":"💪📜 work-notes: A \"Dotfiles Manager\" For Work-Related Notes","archived":false,"fork":false,"pushed_at":"2025-09-13T21:37:17.000Z","size":23,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T23:35:35.062Z","etag":null,"topics":["dotfiles","knowledge-base","linux","note-taking","notes","stow","unix","work"],"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/sebastiancarlos.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-19T01:33:40.000Z","updated_at":"2025-09-13T21:37:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"72022b01-4bb7-4861-a6ae-a577627315b8","html_url":"https://github.com/sebastiancarlos/work-notes","commit_stats":null,"previous_names":["sebastiancarlos/work-notes"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sebastiancarlos/work-notes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fwork-notes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fwork-notes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fwork-notes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fwork-notes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebastiancarlos","download_url":"https://codeload.github.com/sebastiancarlos/work-notes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastiancarlos%2Fwork-notes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30284776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["dotfiles","knowledge-base","linux","note-taking","notes","stow","unix","work"],"created_at":"2025-09-16T02:57:47.657Z","updated_at":"2026-03-09T06:32:30.331Z","avatar_url":"https://github.com/sebastiancarlos.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💪📜 `work-notes`: A *\"Dotfiles Manager\"* For Work-Related Notes\n\nThis repository contains work-related notes.\n\n\u003cimg height=\"350\" alt=\"venn diagram. left 'dotfiles-style co-location', right 'knowledge-bases', center 'work-notes lives here'\" src=\"https://github.com/user-attachments/assets/a9638a1a-d4e1-4e23-9f70-35ad83a704f3\" /\u003e\n\nIts purpose is to:\n- **Keep all work-related notes together** in a single Git repository, and\n- Provide a mechanism to **co-locate them with the actual work directories**,\n  so they can be easily accessed from an IDE or terminal.\n  - This is done with symbolic links, managed by **[GNU\n    Stow](https://www.gnu.org/software/stow/).**\n\n\u003e Labor · Labor · Labor · Labor · Labor · Labor.\n\u003e\n\u003e Dixit · Mihi · Necesse · Esse\n\u003e\n\u003e Labor · Labor · Labor · Labor · Labor · Labor.\n\u003e\n\u003e Vidit · Me · Facientem · Meum\n\u003e\n\u003e Lutum · Lutum · Lutum · Lutum · Lutum · Lutum.\n\u003e \n\u003e *- \"Work\" by Rihanna (2016), translated to Latin.*\n\n## Is this tool for me?\n\nIf you answer \"yes\" to the following questions, then this tool might be for\nyou:\n\n- Do you use the UNIX terminal?\n- Do you want to keep your work-related notes as text files?\n- Do you want to keep them all together under source control?\n- Do you also want to co-locate them with your work directories/repos?\n\n## Dependencies\n\n- Bash,\n- [GNU Stow](https://www.gnu.org/software/stow/), and\n- [fzf](https://github.com/junegunn/fzf) (optional, only for the `work-notes`\n  script).\n\n## Overview\n\nThe notes are files stored in a `./base` directory tree, and GNU Stow symlinks\nthem in the corresponding `~/work/\u003cclient\u003e/\u003cproject\u003e` directories.\n\nThe installation target is `~/work`, but this can be changed in the `install`\nscript. \n\nIn principle, this is the same as the tried-and-true formula of having a\nversion-controlled *dotfiles* directory, and using GNU Stow to symlink it to\nthe home directory, but applied to the problem of work-related notes.\n\nIn other words: Just like a *dotfiles manager* is little more than a GNU Stow\nwrapper with some dotfile-specific functionality, `work-notes` is just a GNU\nStow wrapper with some work-note-specific functionality.\n\nWhile this is not strictly limited to \"work-related\" notes, the term was\npicked because:\n- For generic notes, or \"knowledge base\" management, you usually don't have to\n  co-locate the notes anywhere else.\n- For personal projects, or projects in which there is just one or two people\n  on the same remote repository, the presence of an actual uncommitted notes\n  file in the directory is not much of a problem.\n- This pattern is most useful for \"work-related\" projects where you have\n  multiple people working on the same repository, you don't want to\n  accidentally commit your personal notes, and you also don't want to alter\n  the `.gitignore` file just to fit your personal needs.\n- It's the actual use-case that made me create this tool.\n\nThe examples below assume that this repo is located on `~/work/notes`, but\nthis is not a requirement. (GNU Stow assumes by default that the target is the\nparent directory of the repository, so this fits.)\n\n## Structure\n\nAll notes live inside the `./base` directory, which mirrors the structure of\nthe target `~/work`.\n\n### Sample `work-notes` directory structure\n\n```\n~/work/notes/\n├── base/\n│   └── \u003cclient-name\u003e/\n│       ├── \u003cproject-name\u003e/\n│       │   └── notes.md\n│       └── notes.md\n├── install*\n├── uninstall*\n├── new-work-notes*\n└── work-notes*\n```\n\n### Sample target directory structure\n\n```\n~/work/\n└── \u003cclient-name\u003e/\n    ├── \u003cproject-name\u003e/\n    │   ├── notes.md (SYMLINK to ~/work/notes/...)\n    │   └── project repo files...\n    └── notes.md (SYMLINK to ~/work/notes/...)\n```\n\nThe actual directory structure can be anything, but a recommendation is to\nhave the following kinds of notes, depending on the work requirements:\n- `~/work/\u003cclient-name\u003e/notes.md`\n- `~/work/\u003cclient-name\u003e/\u003cproject-name\u003e/notes.md`\n- `~/work/\u003cclient-name\u003e/\u003cproject-name\u003e/\u003crepo-name\u003e/notes.md`\n- `~/work/\u003cclient-name\u003e/\u003crepo-name\u003e/notes.md`\n  - This one is useful when a client has a few repos, and there's no need to\n    group them by project.\n\n## Setup\n\n- Install GNU Stow if not already installed:\n  - MacOS: `brew install stow`\n  - Linux: `sudo apt-get install stow`\n  - Arch (btw): `sudo pacman -S stow`\n- Clone this repository to `~/work/notes`.\n  - **Note:** If actually using it for work-related notes, make sure to keep\n    it offline, or make it private. And naturally, care must be taken to\n    comply with any contractual requirements to purge work-related information\n    after your work concludes.\n- Create directories in `base/` matching those of your work directory.\n- Add your notes in the corresponding directories.\n- Run `./install` to create the symlinks in the corresponding `~/work`\n  directories.\n- Optionally run `make` to install the `work-notes` script to your `$PATH`.\n  (See `Makefile` for details.)\n\n## Workflow \u0026 Scripts\n\n### `install`\n\nThis script runs `stow base` to create or update the symlinks in the `~/work`\ndirectory. Run it after adding new note files to create the corresponding\nsymlinks.\n\n### `install`\n\nScript to (temporarily?) remove the symlinks created by `install`. Useful if\nyou want to have a work directory temporarily clean of your personal notes.\n\n### `new-work-notes \u003cpath\u003e`\n\nCreates a new note file and its parent directories within the `base`\nstructure.\n\n- To create a default `notes.md`:\n  ```bash\n  # Creates base/client-x/project-y/notes.md\n  new-work-notes client-x/project-y\n  ```\n- To create a note file with a custom name:\n  ```bash\n  # Creates base/client-x/project-y/meetings.md\n  new-work-notes client-x/project-y/meetings.md\n  ```\n\nAfter creating a new note, run `./install` to link it. **Note:** This is not\ndone automatically so that the user can review that the file was created as\nintended before linking it.\n\n### `work-notes \u003cprefix\u003e`\n\nLaunches an `fzf` fuzzy-finder TUI scoped to your notes directory (`./base`).\nIf an optional `[prefix]` is provided, it's used as the initial search query.\nIt opens it in your default `$EDITOR`.\n\n```bash\n# Finds and opens base/client-x/project-y/notes.md\nwork-notes client-x/proj\n```\n\n## Git Integration\n\nTo prevent these symlinked note files from appearing in your project\nrepositories' `git status`, add them to a global gitignore file.\n\n## Best practices\n\nWhen using `work-notes`, your work directory contains only symlinks to your\nnotes. This implies the following:\n\n#### If you want to edit a note...\nDo it as usual: `vim ~/work/some-project/notes.md`. It will follow the symlink\nand edit the source file.\n\n#### If you want to add, delete, or move notes...\nYou will need to do it in the source folder, and then run `./install` to sync\nthe changes. The symlinks for the deleted file will be removed from your work\nfolder.\n\n## F.A.Q.\n\n#### Why use GNU Stow?\n\nI used Stow to save a little bit of development time. Stow already comes with\ngood verbose logging, fails with an error message if conflicts are detected,\nand removes dead symlinks on update. Basically, it was convenient to build on\ntop of something that I didn't have to debug.\n\n#### Can I change the `work-notes` folder name?\n\nYes. Just rename it. Everything will keep working fine - the scripts don't\nrely on a specific folder name.\n\n## Prior art\n- https://dev.to/futurice/how-i-handle-my-notes-with-symbolic-links-594j\n- [Dotfiles Linked To Higher OKRs in Placebo-Controlled\n  Study](https://www.youtube.com/watch?v=dQw4w9WgXcQ)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastiancarlos%2Fwork-notes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebastiancarlos%2Fwork-notes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastiancarlos%2Fwork-notes/lists"}