mirror of
https://github.com/jrnl-org/jrnl.git
synced 2025-05-10 16:48:31 +02:00
422 lines
17 KiB
HTML
422 lines
17 KiB
HTML
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>jrnl</title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="">
|
|
<meta name="author" content="Manuel Ebert">
|
|
<link rel="shortcut icon" href="img/favicon.ico">
|
|
<!-- Le styles -->
|
|
<link href="css/bootstrap.min.css" rel="stylesheet">
|
|
<link href="css/jrnl.css" rel="stylesheet">
|
|
<style>
|
|
body {
|
|
padding-top: 60px; /* 60px to make the container go all the way to the bottom of the topbar */
|
|
}
|
|
</style>
|
|
|
|
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
|
|
<!--[if lt IE 9]>
|
|
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
|
|
<link rel="shortcut icon" href="img/favicon.png">
|
|
|
|
<script type="text/javascript">
|
|
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-30926613-1']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
|
|
</script>
|
|
|
|
</head>
|
|
|
|
<body data-spy="scroll">
|
|
|
|
<a href="http://github.com/maebert/jrnl"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://a248.e.akamai.net/assets.github.com/img/7afbc8b248c68eb468279e8c17986ad46549fb71/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6461726b626c75655f3132313632312e706e67" alt="Fork me on GitHub"></a>
|
|
|
|
<div class="container">
|
|
<div class="logo row">
|
|
<div class="span2"> </div>
|
|
<div class="span10"><img src="img/logo-top.png" title="jrnl - the friendly Command Jine Journal"/></div>
|
|
</div>
|
|
<div class="row">
|
|
|
|
<div class="span2 navcontain">
|
|
<a href="#" title="Top"><div class="leftlogo"></div></a>
|
|
<div class="sidebar-nav" id='navbar'>
|
|
<ul class="nav nav-list">
|
|
|
|
</ul>
|
|
</div>
|
|
|
|
</div>
|
|
<div class="span10 content">
|
|
<h1>jrnl</h1>
|
|
|
|
<p><em>jrnl</em> is a simple journal application for your command line. Journals are stored as human readable plain text files - you can put them into a Dropbox folder for instant syncing and you can be assured that your journal will still be readable in 2050, when all your fancy iPad journal applications will long be forgotten.</p>
|
|
|
|
<p><em>jrnl</em> also plays nice with the fabulous <a href="http://dayoneapp.com/">DayOne</a> and can read and write directly from and to DayOne Journals.</p>
|
|
|
|
<p>Optionally, your journal can be encrypted using the <a href="http://en.wikipedia.org/wiki/Advanced_Encryption_Standard">256-bit AES</a>.</p>
|
|
|
|
<h3>Why keep a journal?</h3>
|
|
|
|
<p>Journals aren't only for 13-year old girls and people who have too much time on their summer vacation. A journal helps you to keep track of the things you get done and how you did them. Your imagination may be limitless, but your memory isn't. For personal use, make it a good habit to write at least 20 words a day. Just to reflect what made this day special, why you haven't wasted it. For professional use, consider a text-based journal to be the perfect complement to your GTD todo list - a documentation of what and how you've done it.</p>
|
|
|
|
<h2>In a Nutshell</h2>
|
|
|
|
<p>to make a new entry, just type</p>
|
|
|
|
<pre><code>jrnl yesterday: Called in sick. Used the time to clean the house and spent 4h on writing my book.
|
|
</code></pre>
|
|
|
|
<p>and hit return. <code>yesterday:</code> will be interpreted as a timestamp. Everything until the first sentence mark (<code>.?!</code>) will be interpreted as the title, the rest as the body. In your journal file, the result will look like this:</p>
|
|
|
|
<pre><code>2012-03-29 09:00 Called in sick.
|
|
Used the time to clean the house and spent 4h on writing my book.
|
|
</code></pre>
|
|
|
|
<p>If you just call <code>jrnl</code>, you will be prompted to compose your entry - but you can also configure <em>jrnl</em> to use your external editor.</p>
|
|
|
|
<h2>Installation</h2>
|
|
|
|
<p>Install <em>jrnl</em> using pip:</p>
|
|
|
|
<pre><code>pip install jrnl
|
|
</code></pre>
|
|
|
|
<p>Alternatively, install manually by cloning the repository:</p>
|
|
|
|
<pre><code>git clone git://github.com/maebert/jrnl.git
|
|
cd jrnl
|
|
python setup.py install
|
|
</code></pre>
|
|
|
|
<p>The first time you run <code>jrnl</code> you will be asked where your journal file should be created and whether you wish to encrypt it.</p>
|
|
|
|
<h2>Usage</h2>
|
|
|
|
<p><em>jrnl</em> has to modes: <strong>composing</strong> and <strong>viewing</strong>. </p>
|
|
|
|
<h3>Viewing:</h3>
|
|
|
|
<pre><code>jrnl -n 10
|
|
</code></pre>
|
|
|
|
<p>will list you the ten latest entries,</p>
|
|
|
|
<pre><code>jrnl -from "last year" -to march
|
|
</code></pre>
|
|
|
|
<p>everything that happened from the start of last year to the start of last march. If you only want to see the titles of your entries, use</p>
|
|
|
|
<pre><code>jrnl -short
|
|
</code></pre>
|
|
|
|
<h3>Using Tags:</h3>
|
|
|
|
<p>Keep track of people, projects or locations, by tagging them with an <code>@</code> in your entries:</p>
|
|
|
|
<pre><code>jrnl Had a wonderful day on the #beach with @Tom and @Anna.
|
|
</code></pre>
|
|
|
|
<p>You can filter your journal entries just like this:</p>
|
|
|
|
<pre><code>jrnl @pinkie @WorldDomination
|
|
</code></pre>
|
|
|
|
<p>Will print all entries in which either <code>@pinkie</code> or <code>@WorldDomination</code> occurred.</p>
|
|
|
|
<pre><code>jrnl -n 5 -and @pineapple @lubricant
|
|
</code></pre>
|
|
|
|
<p>the last five entries containing both <code>@pineapple</code> <strong>and</strong> <code>@lubricant</code>. You can change which symbols you'd like to use for tagging in the configuration.</p>
|
|
|
|
<blockquote>
|
|
<p><strong>Note:</strong> <code>jrnl @pinkie @WorldDomination</code> will switch to viewing mode because although now command line arguments are given, all the input strings look like tags - <em>jrnl</em> will assume you want to filter by tag. </p>
|
|
</blockquote>
|
|
|
|
<h3>Smart timestamps:</h3>
|
|
|
|
<p>Timestamps that work:</p>
|
|
|
|
<ul>
|
|
<li>at 6am</li>
|
|
<li>yesterday</li>
|
|
<li>last monday</li>
|
|
<li>sunday at noon</li>
|
|
<li>2 march 2012</li>
|
|
<li>7 apr</li>
|
|
<li>5/20/1998 at 23:42</li>
|
|
</ul>
|
|
|
|
<h2>Import and export</h2>
|
|
|
|
<h3>Tag export</h3>
|
|
|
|
<p>With</p>
|
|
|
|
<pre><code>jrnl --tags
|
|
</code></pre>
|
|
|
|
<p>you'll get a list of all tags you used in your journal, sorted by most frequent. Tags occuring several times in the same entry are only counted as one.</p>
|
|
|
|
<h3>JSON export</h3>
|
|
|
|
<p>Can do:</p>
|
|
|
|
<pre><code>jrnl --json
|
|
</code></pre>
|
|
|
|
<p>Why not create a beautiful <a href="http://timeline.verite.co/">timeline</a> of your journal?</p>
|
|
|
|
<h3>Markdown export</h3>
|
|
|
|
<pre><code>jrnl --markdown
|
|
</code></pre>
|
|
|
|
<p>Markdown is a simple markup language that is human readable and can be used to be rendered to other formats (html, pdf). This README for example is formatted in markdown and github makes it look nice.</p>
|
|
|
|
<h2>Encryption</h2>
|
|
|
|
<p>If you don't choose to encrypt your file when you run <code>jrnl</code> for the first time, you can encrypt your existing journal file or change its password using</p>
|
|
|
|
<pre><code>jrnl --encrypt
|
|
</code></pre>
|
|
|
|
<p>If it is already encrypted, you will first be asked for the current password. You can then enter a new password and your plain journal will replaced by the encrypted file. Conversely,</p>
|
|
|
|
<pre><code>jrnl --decrypt
|
|
</code></pre>
|
|
|
|
<p>will replace your encrypted journal file by a Journal in plain text. You can also specify a filename, ie. <code>jrnl --decrypt plain_text_copy.txt</code>, to leave your original file untouched.</p>
|
|
|
|
<h2>Advanced usages</h2>
|
|
|
|
<p>The first time launched, <em>jrnl</em> will create a file called <code>.jrnl_config</code> in your home directory.</p>
|
|
|
|
<h3>.jrnl_config</h3>
|
|
|
|
<p>The configuration file is a simple JSON file with the following options.</p>
|
|
|
|
<ul>
|
|
<li><code>journals</code>: paths to your journal files</li>
|
|
<li><code>editor</code>: if set, executes this command to launch an external editor for writing your entries, e.g. <code>vim</code> or <code>subl -w</code> (note the <code>-w</code> flag to make sure <em>jrnl</em> waits for Sublime Text to close the file before writing into the journal).</li>
|
|
<li><code>encrypt</code>: if <code>true</code>, encrypts your journal using AES.</li>
|
|
<li><code>password</code>: you may store the password you used to encrypt your journal in plaintext here. This is useful if your journal file lives in an unsecure space (ie. your Dropbox), but the config file itself is more or less safe.</li>
|
|
<li><code>tagsymbols</code>: Symbols to be interpreted as tags. (<strong>See note below</strong>)</li>
|
|
<li><code>default_hour</code> and <code>default_minute</code>: if you supply a date, such as <code>last thursday</code>, but no specific time, the entry will be created at this time</li>
|
|
<li><code>timeformat</code>: how to format the timestamps in your journal, see the <a href="http://docs.python.org/library/time.html#time.strftime">python docs</a> for reference</li>
|
|
<li><code>highlight</code>: if <code>true</code> and you have <a href="http://www.nicosphere.net/clint-command-line-library-for-python/">clint</a> installed, tags will be highlighted in cyan. </li>
|
|
<li><code>linewrap</code>: controls the width of the output. Set to <code>0</code> or <code>false</code> if you don't want to wrap long lines.</li>
|
|
</ul>
|
|
|
|
<blockquote>
|
|
<p><strong>Note on <code>tagsymbols</code>:</strong> Although it seems intuitive to use the <code>#</code> character for tags, there's a drawback: on most shells, this is interpreted as a meta-character starting a comment. This means that if you type</p>
|
|
|
|
<pre><code>jrnl Implemented endless scrolling on the #frontend of our website.
|
|
</code></pre>
|
|
|
|
<p>your bash will chop off everything after the <code>#</code> before passing it to <em>jrnl</em>). To avoid this, wrap your input into quotation marks like this:</p>
|
|
|
|
<pre><code>jrnl "Implemented endless scrolling on the #frontend of our website."
|
|
</code></pre>
|
|
|
|
<p>Or use the built-in prompt or an external editor to compose your entries.</p>
|
|
</blockquote>
|
|
|
|
<h3>DayOne Integration</h3>
|
|
|
|
<p>Using your DayOne journal instead of a flat text file is dead simple - instead of pointing to a text file, set the <code>"journal"</code> key in your <code>.jrnl_conf</code> to point to your DayOne journal. This is a folder ending with <code>.dayone</code>, and it's located at</p>
|
|
|
|
<pre><code>* `~/Library/Application Support/Day One/` by default
|
|
* `~/Dropbox/Apps/Day One/` if you're syncing with Dropbox and
|
|
* `~/Library/Mobile Documents/5U8NS4GX82~com~dayoneapp~dayone/Documents/` if you're syncing with iCloud.
|
|
</code></pre>
|
|
|
|
<p>Instead of all entries being in a single file, each entry will live in a separate <code>plist</code> file. You can also star entries when you write them:</p>
|
|
|
|
<pre><code>jrnl -star yesterday: Lunch with @Arthur
|
|
</code></pre>
|
|
|
|
<h3>Multiple journal files</h3>
|
|
|
|
<p>You can configure <em>jrnl</em> to use with multiple journals (eg. <code>private</code> and <code>work</code>) by defining more journals in your <code>.jrnl_config</code>, for example:</p>
|
|
|
|
<pre><code>"journals": {
|
|
"default": "~/journal.txt",
|
|
"work": "~/work.txt"
|
|
},
|
|
</code></pre>
|
|
|
|
<p>The <code>default</code> journal gets created the first time you start <em>jrnl</em>. Now you can access the <code>work</code> journal by using <code>jrnl work</code> instead of <code>jrnl</code>, eg. </p>
|
|
|
|
<pre><code>jrnl work at 10am: Meeting with @Steve
|
|
jrnl work -n 3
|
|
</code></pre>
|
|
|
|
<p>will both use <code>~/work.txt</code>, while <code>jrnl -n 3</code> will display the last three entries from <code>~/journal.txt</code> (and so does <code>jrnl default -n 3</code>).</p>
|
|
|
|
<p>You can also override the default options for each individual journal. If you <code>.jrnl_conf</code> looks like this:
|
|
{
|
|
...
|
|
"encrypt": false
|
|
"journals": {
|
|
"default": "~/journal.txt",
|
|
"work": {
|
|
"journal": "~/work.txt",
|
|
"encrypt": true
|
|
},
|
|
"food": "~/my_recipes.txt",
|
|
}</p>
|
|
|
|
<p>Your <code>default</code> and your <code>food</code> journals won't be encrypted, however your <code>work</code> journal will! You can override all options that are present at the top level of <code>.jrnl_conf</code>, just make sure that at the very least you specify a <code>"journal": ...</code> key that points to the journal file of that journal.</p>
|
|
|
|
<h3>Manual decryption</h3>
|
|
|
|
<p>Should you ever want to decrypt your journal manually, you can do so with any program that supports the AES algorithm. The key used for encryption is the SHA-256-hash of your password, and the IV (initialisation vector) is stored in the first 16 bytes of the encrypted file. So, to decrypt a journal file in python, run</p>
|
|
|
|
<pre><code>import hashlib, Crypto.Cipher
|
|
key = hashlib.sha256(my_password).digest()
|
|
with open("my_journal.txt") as f:
|
|
cipher = f.read()
|
|
crypto = AES.new(key, AES.MODE_CBC, iv = cipher[:16])
|
|
plain = crypto.decrypt(cipher[16:])
|
|
</code></pre>
|
|
|
|
<h2>Known Issues</h2>
|
|
|
|
<ul>
|
|
<li>The Windows shell prior to Windows 7 has issues with unicode encoding. If you want to use non-ascii characters, change the codepage with <code>chcp 1252</code> before using <code>jrnl</code> (Thanks to Yves Pouplard for solving this!)</li>
|
|
<li><em>jrnl</em> relies on the <code>Crypto</code> package to encrypt journals, which has some known problems with installing within virtual environments.</li>
|
|
</ul>
|
|
<h1>Changelog</h1>
|
|
|
|
<h3>1.0.0 (March 4, 2013)</h3>
|
|
|
|
<ul>
|
|
<li>[New] Integrates seamlessly with DayOne</li>
|
|
<li>[Improved] Each journal can have individual settings</li>
|
|
<li>[Fixed] A bug where jrnl would not go into compose mode</li>
|
|
<li>[Fixed] A bug where jrnl would not add entries without timestamp</li>
|
|
<li>[Fixed] Support for parsedatetime 1.x</li>
|
|
</ul>
|
|
|
|
<h3>0.3.2 (July 5, 2012)</h3>
|
|
|
|
<ul>
|
|
<li>[Improved] Converts <code>\n</code> to new lines (if using directly on a command line, make sure to wrap your entry with quotes).</li>
|
|
</ul>
|
|
|
|
<h3>0.3.1 (June 16, 2012)</h3>
|
|
|
|
<ul>
|
|
<li>[Improved] Supports deleting of last entry.</li>
|
|
<li>[Fixed] Fixes a bug where --encrypt or --decrypt without a target file would not work.</li>
|
|
<li>[Improved] Supports a config option for setting word wrap.</li>
|
|
<li>[Improved] Supports multiple journal files.</li>
|
|
</ul>
|
|
|
|
<h3>0.3.0 (May 24, 2012)</h3>
|
|
|
|
<ul>
|
|
<li>[Fixed] Dates such as "May 3" will now be interpreted as being in the past if the current day is at least 28 days in the future</li>
|
|
<li>[Fixed] Bug where composed entry is lost when the journal file fails to load</li>
|
|
<li>Changed directory structure and install scripts (removing the necessity to make an alias from <code>jrnl</code> to <code>jrnl.py</code>)</li>
|
|
</ul>
|
|
|
|
<h4>0.2.4 (May 21, 2012)</h4>
|
|
|
|
<ul>
|
|
<li>[Fixed] Parsing of new lines in journal files and entries</li>
|
|
<li>[Improved] Adds support for encrypting and decrypting into new files</li>
|
|
</ul>
|
|
|
|
<h4>0.2.3 (May 3, 2012)</h4>
|
|
|
|
<ul>
|
|
<li>[Improved] Adds a <code>-short</code> option that will only display the titles of entries (or, when filtering by tags, the context of the tag)</li>
|
|
<li>[Improved] Adds tag export</li>
|
|
<li>[Improved] Adds coloured highlight of tags (by default, highlights all tags - when filtering by tags, only highlights search tags)</li>
|
|
<li>[Improved] <code>.jrnl_config</code> will get automatically updated when updating jrnl to a new version</li>
|
|
</ul>
|
|
|
|
<h4>0.2.2 (April 17, 2012)</h4>
|
|
|
|
<ul>
|
|
<li>[Improved] Adds --encrypt and --decrypt to encrypt / decrypt existing journal files</li>
|
|
<li>[Improved] Adds markdown export (kudos to dedan)</li>
|
|
</ul>
|
|
|
|
<h4>0.2.1 (April 17, 2012)</h4>
|
|
|
|
<ul>
|
|
<li>[Improved] Submitted to <a href="http://pypi.python.org/pypi/jrnl/0.2.1">PyPi</a>.</li>
|
|
</ul>
|
|
|
|
<h3>0.2.0 (April 16, 2012)</h3>
|
|
|
|
<ul>
|
|
<li>[Improved] Encrypts using CBC</li>
|
|
<li>[Fixed] <code>key</code> has been renamed to <code>password</code> in config to avoid confusion. (The key use to encrypt and decrypt a journal is the SHA256-hash of the password.)</li>
|
|
</ul>
|
|
|
|
<h4>0.1.1 (April 15, 2012)</h4>
|
|
|
|
<ul>
|
|
<li>[Fixed] Removed unnecessary print commands</li>
|
|
<li>[Improved] Created the documentation</li>
|
|
</ul>
|
|
|
|
<h3>0.1.0 (April 13, 2012)</h3>
|
|
|
|
<ul>
|
|
<li>[Improved] Supports encrypted journals using AES encryption</li>
|
|
<li>[Improved] Support external editors for composing entries</li>
|
|
</ul>
|
|
|
|
<h4>0.0.2 (April 5, 2012)</h4>
|
|
|
|
<ul>
|
|
<li>[Improved] Filtering by tags and dates</li>
|
|
<li>[Fixed] Now using dedicated classes for Journals and entries</li>
|
|
</ul>
|
|
|
|
<h4>0.0.1 (March 29, 2012)</h4>
|
|
|
|
<ul>
|
|
<li>Composing entries works. That's pretty much it.</li>
|
|
</ul>
|
|
|
|
</div> <!-- /span10 -->
|
|
|
|
<div class="row">
|
|
<footer class="span10 offset2">
|
|
<b>jrnl</b> is an open source project created with love by <a href="http://www.portwempreludium.de">Manuel Ebert</a> and <a href="http://www.github.com/dedan">Stephan Gabler</a>.
|
|
</footer>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
</div> <!-- /container -->
|
|
|
|
<!-- Le javascript
|
|
================================================== -->
|
|
<!-- Placed at the end of the document so the pages load faster -->
|
|
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
|
|
<script src="js/jrnl.js"></script>
|
|
<script src="js/bootstrap.min.js"></script>
|
|
|
|
</body>
|
|
</html>
|