The system-wide Org file manager
Project description
Torgo is the system-wide org file manager. It allows you to create org-mode files that are associated with whatever directory you are in, but which are managed externally.
Usage
usage: torgo [-h] [-l] [-t] [-i] [-p] [command] [param]
Org-file anywhere, managed
positional arguments:
command The command to run
param Optional param for commands, see commands list for more
information
optional arguments:
-h, --help show this help message and exit
-l, --list List the commands available
-t, --this Use 'this' directory, don't attempt to find org file in parents
-i, --init Force a re-init of the configuration
-p, --prune Prune the current org file (delete it)
Wherever you run torgo, torgo will create a managed org-mode file for the directory you are in. This org-mode file will be stored in a central location, but will be associated with the directory torgo was called from.
Configuration
When torgo is first ran, it will walk you through a configuration file
creation process. This configuration file defaults to ~/.torgo.cfg
, but you
can override that with the $TORGO_CFG
environment variable.
The config file defines the following settings:
org_dir
: This is the path to where your org files will go. It defaults to~/.torgo/
.editor
: This is your desired text editor. If blank, will attempt to use$EDITOR
from your environment.ext
: This is the desired org file extension. It defaults toorg
.
You can force torgo to re-initialize the configuration by passing the
-i
/--init
option.
How does it work?
Perhaps the best way to understand how to use torgo, is to see how it works.
When torgo is run, it starts in the current working directory and checks if
an org file entry exists for that directory in its flat database file (by
default, this is ~/.torgo/org_lookup_db.json
). If no org-file is found, it
steps up to the parent directory and checks there. It repeats this until it
either finds an org file or reaches root. If it reaches root, then it takes
the original working directory as the one for the org-mode.
Note: You can force it to use the current working directory by passing the
-t
/--this
parameter.
Once it has the appropriate org-mode file it fires up your editor of choice on that file. You edit the file, take your notes or whatever, and save it.
The next time you fire up torgo in that same directory (or in a sub-directory) it will load the same org-mode file.
Tagging
Each org file can be tagged with any number of tags. To set or unset the tags,
use the tag
command. Tags are a comma-separated list of parameters after
the tag command. Tags with a .
(period/dot) prefix will be unset. To list
the tags for a given org file, call tag without any parameters.
> torgo tag foo,bar,baz
> torgo tag
The tags associated with this org file:
foo
bar
baz
> torgo tag .bar
> torgo tag
The tags associated with this org file:
foo
baz
Once tagged, you can search for all the paths which have org files associated
with a given list of tags using the search
command using a list of tags as
its parameter.
> torgo search tag=foo,bar
Found 3 records with the following tags:
foo
bar
Path: /home/sam/work/torgo | [oss, python, foo]
Path: /home/sam/work/bigdeal | [bar, work]
Path: /home/sam/meh | [oss, github, dotfiles, foo, bar]
Does it have to be org-mode files?
No! Simply change the ext
in the configuration file to whatever extension
you'd like. Torgo doesn't force any file type on you, it just manages the
files associated with your directories. If you would rather take your notes
in Markdown, plain-text, or anything else, you're free to do so.
Why is it called Torgo?
For a while, I had been using a this.org
pattern for my ad-hoc org files.
Say I was in a directory that was a repo for a project I was on and suddenly
needed to take notes- I'd do a vim .this.org
and write my notes in it. Or
say I was configuring something in the system and needed to take notes on
what I was doing- Again, I'd do a vim .this.org
.
This pattern worked well because I'd always be able to have contextual org-mode note files wherever I was. But it had a number of downsides.
For one, it littered my directories with .this.org
files. If a directory
was a repo, I'd generally have to add .this.org
to its ignore file. Further,
I'd have no way to easily backup or version control all of my .this.org
files.
I created a hacky shell script that would let me have system-wide org-mode files
in my home-directory that would be associated by hashes of the directories I
was in. This let me keep my this.org
pattern, but not litter my directories.
It also let me version control my this.org
files and back them up easily.
Originally, this shell script was called torg
(from this.org
). As I started
refining it, and extending it, I eventually decided I should re-write it in
Python. Since I was a MST3k fan, and since Manos The Hands of Fate is the
greatest movie of all time, it was an easy leap to go from this.org
, to torg
,
to torgo
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.