The .docsfile

Today I came up with an interesting idea while working on a project. I’m sure this isn’t a profoundly novel idea, but it felt worth sharing.

Often while working within a repository, there will be a list of documentation URLs that I use. These URLs typically vary per-repository and if the documentation is separate from the repository itself, I then have to hunt for the docs in my bookmarks or confluence or what-have-you.

So it occurred to me: what if I had a flexible way to assign arbitrary documentation that I could easily access from the command line? So I slapped on my bashing-coding hat and came up with this:

# Utility function to allow us to open the documentation for the current project
function docs() {
   if [[ -f ".docsfile" ]]; then
      open $(cat .docsfile)
   else
      vim -c ':exe "normal i# Replace this line with the URL to this projects documentation"' .docsfile
      [[ -f ".docsfile" ]] && echo ".docsfile" >> .git/info/exclude
   fi
}

So now inside any repo, I can just run docs to access any documentation needs.

This script is auto-loaded in my dotfiles so I have access to it any time I’m in a session where my dotfiles are loaded.

Here’s the highlights:

• If a .docsfile is present in the working directory, open it.
• Otherwise, creates a new .docsfile, and dump some instructions into it
• If the user saves their work, it adds the .docsfile to the .git/info/exclude file which doesn’t commit it to the repository, that way it doesn’t touch anyone else!
• Otherwise, is user doesn’t save the file, it does nothing.

A few ideas to improve it:

• Add a mechanism to select from multiple docs either via passing a keyword or maybe using fzf
• Figure out how to add that damn comma in “projects” without breaking the vim command. 🤔