An interactive commandline interface for your personal docs using python, Cmd, git and markdown
Project description
cmddocs is an interactive commandline wiki. It lets you easily maintain your docs/cheetsheets/notes using:
Plain Text Files
Write markdown in your local Editor
View in your local Pager
Versioning with git
cmddocs is like a framework around your plaintext files.
Why ?
I kind of started cmddocs because I couldn’t find something like this on the internet. Here’s my usecase. Im working as a DevOps guy being in touch with various types of software, languages, tools, operating systems and databases. To remember all those things I need a place to store commands, workflows and short howtos.
Most of the software I use (and love) runs on a OpenBSD Box on the internet and are commandline-based. These are mutt, taskwarrior, jrnl, weechat and so on…But i was missing a tool for documentation.
After switching to just plaintext files using vim and git it was also a bit annoying. So I wrote cmddocs to make it easier for me to handle my plaintext files.
Demo
To give you an idea what it looks/feels like I created a short terminal recording.
Installation
pip install cmddocs
Also make sure you have tree installed.
Configuration
Create .cmddocsrc file in your $HOME with the following content (adjust to your needs):
[General] Datadir = /home/noqqe/Docs Default_Commit_Message = small changes Excludedir = .git/ Editor = /usr/local/bin/vim Pager = /usr/bin/less PagerFlags = -fr Prompt = cmddocs> Promptcolor = 37 Intro_Message = cmddocs - press ? for help Mail = mail@example.org Default_Extension = md [Colors] Header12 = 37 Header345 = 37 Codeblock = 92
The only required option is “Datadir”, everything else will be guessed or defaults to a sane default value. Once you start cmddocs.py the CLI will be shown. Use help for commands.
Quick Start
At first, create a very minimal config, like
[General] Datadir = /home/noqqe/Docs Editor = /usr/local/bin/vim Pager = /usr/bin/less
Then you can start using cmddocs.
$ cmddocs
cmddocs - press ? for help
cmddocs> help
Documented commands (type help <topic>):
========================================
EOF delete e help list mail pwd search undo
cd diff edit info log move revert stats version
d dirs exit l ls mv rm status view
cmddocs> help l
Show files in current working dir
cmddocs> help log
Show git logs of your docs.
Usage: log # default loglines: 10)
log 20 # show 20 loglines
log 20 article # show log for specific article
log databases/mongodb 3 # same
Command Documentation
cd
Change directory
Usage:
cd Programming/
cd
delete, rm
Delete an article
Usage:
delete databases/mongodb
rm databases/mssql
dirs, d
Show directories in current working dir
Usage:
dirs
d
dirs Databases/
e, edit
Edit or create new article.
Usage:
edit databases/mongodb
edit intro
list, l, ls
Show files in current working dir
Usage:
list
l
list Databases/
move, mv
Move an article to a new location
Usage:
move databases/mongodb databases/MongoDB
move life/foo notes/foo
mv life/foo notes/foo
view
View an article. Creates temporary file with converted markdown to ansi colored output. Opens your PAGER. (Only less supported atm)
Usage:
view databases/mongodb
view intro
Mail an article to a friend
Usage:
mail databases/mongodb
Recipient: mail@example.net
mail programming/r/loops
mail intro
pwd
Show current directory
Usage:
pwd
search
Search for keyword in current directory
Usage:
search mongodb
search foo
undo, revert
You can revert your changes (use revert from git)
Usage:
undo HEAD
undo 355f375
Will ask for confirmation.
diff
Show git diffs between files and commits
Usage:
diff 7 # show diff for last 7 changes
diff 1 article # show diff for last change to article
diff # show last 5 diffs
info
Show infos for an article
Usage:
info article
info Databases/mongodb
Created: 2014-01-18 11:18:03 +0100
Updated: 2015-10-23 14:14:44 +0200
Commits: 26
Lines: 116
Words: 356
Characters: 2438
log
Show git logs of your docs.
Usage:
log # default loglines: 10)
log 20 # show 20 loglines
log 20 article # show log for specific article
log databases/mongodb 3 # same
status
Show git repo status of your docs
Usage:
status
stats
Calculate some statistics on your docs
Usage:
stats
exit, EOF
Exit cmddocs
Usage:
exit
help
List available commands with “help” or detailed help with “help cmd”.
version
Show version of cmddocs
Usage:
version
Changelog
See Changelog.
License
See License.
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.
