Org minor mode - 2-way sync org & trello
Table of Contents generated with DocToc
- Rationale
- Emacs version
- Migration
- TL;DR
- Fast setup
- Prefix binding override in one shot
- Demo
- Synchronize one entity
- Install
- Setup key and token
- Attach org file to trello board
- Synchronize one complete entity
- Synchronize from org to trello
- Sync from trello to org (new format)
- Synchronize from trello to org (old format)
- Create board and sync
- Create board with your keywords
- Use the checkbox Luke
- Kill entities
- Cleanup routine
- org-trello - webadmin
- Simple help routine
- Check your Setup
- Assign oneself to the card
- Contributions
- Release notes
- Install
- Setup
- Bindings
- Use cases
- Errors
- proxy-admin
- Mailing list
- License
- org-mode is what I need.
- Trello is what my team need.
- org-trello is the middle ground!
This will satisfy org-modians and trelloans won't see any difference!
Tested on:
- GNU Emacs 24.3.1 (x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars) of 2013-04-14 on marid, modified by Debian (from 0.1.0)
- GNU Emacs 24.3.1 (x86_64-pc-linux-gnu, GTK+ Version 3.6.0) of 2014-01-03 on chindi02, modified by Debian
The old checklist/item format has been removed - https://github.com/ardumont/org-trello/issues/105. Now the org checkbox way is the standard one.
For information, from 0.2.9 onward, the property "orgtrello-id" from the checkbox (checklists, items) will be hidden.
Note
- Upon activating org-trello minor mode, all existing checkbox will be migrated and should disappear before your eyes.
- Symmetrically, when deactivating org-trello, all checkbox will appear.
- For this, org-trello use overlays (implementation detail which permits to hide buffer region).
If you began to use org-trello, nothing to do.
From 0.2.8 onward, the card description can be synchronized too. Just synchronize as usual.
From the 0.2.2 version onward, we can assign people to card. As a pre-requisite, we need to re-install the board (C-c o I), so that new properties will be installed (users currently assigned to the board we attach to).
This way, you will be able to use the assign (C-c o a) / unassign (C-c o u) yourself to the card.
Org-trello now uses more natural ways of dealing with checklists using checkboxes!
cf. natural org format (from 0.1.6 onwards) for more details.
- From version 0.1.1, some http requests will be asynchronous. For this, we use elnode as a proxy server to make requests to trello. The elnode server is started on the port 9876. You can always change this port
(setq *ORGTRELLO-PROXY-PORT* 9876)Then M-x orgtrello-proxy/reload
Yank this into a scratch buffer:
(require 'package)
(add-to-list 'package-archives '("marmalade" . "http://marmalade-repo.org/packages/"))
(package-initialize)
(package-install 'elnode) ;; for some obscure reason, letting org-trello install elnode's dependencies fail!
(package-install 'org-trello)
(require 'org-trello)
;; to trigger org-trello for each org file
(add-hook 'org-mode-hook 'org-trello-mode)
then M-x eval-buffer
Now open an org-mode buffer, then hit: C-c o h
If you are not happy with "C-c o" as default prefix, you can now override your default prefix keybinding. For this, you need to install the following hook specifying the :
(require 'org-trello)
(add-hook 'org-trello-mode-hook (lambda () (org-trello/install-local-prefix-mode-keybinding! <prefix-key>)))For example, installing using the "C-c x" as prefix key:
(require 'org-trello)
(add-hook 'org-trello-mode-hook (lambda () (org-trello/install-local-prefix-mode-keybinding! "C-c x")))Note If org-trello was already running, you will need to relaunch the mode (M-x org-trello-mode twice).
TODO
- Pull Requests surely welcome (cf. todo - use emacs org-mode buffer to read it)
- Appreciate any feedback
- Open issues if you want something to be done
- Open issues for bugs too (please describe maximum inputs, emacs version, org-trello version, Messages buffer, stacktrace, etc...)
- What has been done and remains to be done
Marmalade one is recommended.
Add this to your emacs's init file (~/.emacs, ~/.emacs.d/init.el, or scratch, or whatnot...)
(require 'package)
(add-to-list 'package-archives '("marmalade" . "http://marmalade-repo.org/packages/"))
(package-initialize)Then hit M-x eval-buffer to evaluate the buffer's contents.
Add this to your emacs's init file (~/.emacs, ~/.emacs.d/init.el, or scratch, or whatnot...)
(require 'package)
(add-to-list 'package-archives '("melpa" . "http://melpa.milkbox.net/packages/") t)
(package-initialize)Then hit M-x eval-buffer to evaluate the buffer's contents.
Note Melpa and Marmalade repositories package the same org-trello code (I try to only merge in master through PR and both release comes from the master branch). The divergence comes from the org-trello dependencies which are not the same version. So surely, the most stable remains marmalade.
To install org-trello, use this:
(when (not package-archive-contents)
(package-refresh-contents))
(defvar my-packages '(elnode org-trello)
"A list of packages installed once at launch.")
(dolist (p my-packages)
(when (not (package-installed-p p))
(package-install p)))Again hit M-x eval-buffer.
Download org-trello from GitHub
git clone http://github.com/ardumont/org-trello.gitAdd the org-trello directory to your load path and then add
(add-to-list 'load-path "/path/to/org-trello/")
(require 'org-trello)Org-trello is a minor mode for org-mode to sync.
Add this somewhere in your load file (~/.emacs or ~/.emacs.d/init.el).
(require 'org-trello)
;; to have org-trello activated for all org file, uncomment this
;; (add-hook 'org-mode-hook 'org-trello-mode)
;; otherwise, M-x org-trello-modeFor example, here is my startup file.
Install the consumer-key and the read-write token for org-trello to be able to work in your name with your trello boards. First, ensure that the web browser that emacs is configured to use is started, and you are logged in to Trello in it.
Then, from an org-mode buffer:
C-c o i
or in any mode:
M-x org-trello/install-key-and-tokenFor each org-mode file, you need to connect your org-mode file with a trello board.
C-c o I
or
M-x org-trello/install-board-and-lists-idsA simpler way could be to create a board from scratch (if you can).
You can avoid the previous step and create directly a board from your org-mode file. This will create the list from the keywords you use in your org-mode (cf. org-todo-keywords).
C-c o b
or
M-x org-trello/create-boardActual bindings (not definitive, suggestions regarding those bindings are welcome):
| Keybindings | Interactive commands | Description |
|---|
| `M-x org-trello/version` | org-trello's current version
C-c o i | M-x org-trello/install-key-and-token | Install the keys and the access-token.
C-c o I | M-x org-trello/install-board-and-lists-ids | Select the board and attach the todo, doing and done list.
C-c o d | M-x org-trello/check-setup | Check that the setup is ok. If everything is ok, will simply display 'Setup ok!'
C-c o D | M-x org-trello/delete-setup | Clean up the org buffer from all org-trello informations
C-c o b | M-x org-trello/create-board | Create interactively a board and attach the org-mode file to this trello board.
C-c o c | M-x org-trello/sync-entity | Create/Update an entity (card/checklist/item) depending on its level and status. Do not deal with level superior to 4.
C-c o C | M-x org-trello/sync-full-entity | Create/Update a complete entity card/checklist/item and its subtree (depending on its level).
C-c o s | M-x org-trello/sync-to-trello | Synchronize the org-mode file to the trello board (org-mode -> trello).
C-c o S | M-x org-trello/sync-from-trello | Synchronize the org-mode file from the trello board (trello -> org-mode).
C-c o k | M-x org-trello/kill-entity | Kill the entity (and its arborescence tree) from the trello board and the org buffer.
C-c o K | M-x org-trello/kill-all-entities | Kill all the entities (and their arborescence tree) from the trello board and the org buffer.
C-c o a | M-x org-trello/assign-me | Assign one-self to the current card
C-c o u | M-x org-trello/unassign-me | Unassign one-self from the current card
C-c o j | M-x org-trello/jump-to-card | Jump to current card
C-c o J | M-x org-trello/jump-to-trello-board | Jump to current trello board
C-c o h | M-x org-trello/help-describing-bindings | This help message.
-
open an org-mode file
-
Install the key and the token file (
C-c o iorM-x org-trello/install-key-and-token). This will open your browser to retrieve the needed information (consumer-keythen theaccess-token) and wait for your input in emacs.
Remark: This only needs to be done once, until you revoke the token.
- Setup your org-mode file with your trello board (
C-c o IorM-x org-trello/install-board-and-lists-ids). This will present you with a list of your actual boards. Select the one you want and hit enter. This will edit your org-mode file to add the properties needed.
Remarks:
- This need to be done once for each org-mode file you want to sync with a trello board.
- You can directly create a board (
C-c o borM-x orgtrello/do-create-board-and-lists)
Now you are ready to use org-mode as usual.
There is a new setup which is activated by default, using the natural org checkboxes. Thanks to @sw1nn for showing me this org feature, this is awesome!.
Activated by default.
- [-] LISP
- [X] Emacs-Lisp
- [X] Common-Lisp
- [ ] Scheme
- [X] Clojure
- [X] ML
- [X] Haskell
- [X] Ocaml
- [X] Hybrid
- [X] Scala
- [ ] little more detail, this is level 2, so checklist in trello board
- [ ] item 3
- [ ] any entities with level superior to 4 are considered level 3
For example, once synced to trello, this looks like:
* IN-PROGRESS Joy of FUN(ctional) LANGUAGES
:PROPERTIES:
:orgtrello-id: 521dc9f3edeabee47600401e
:END:
- [-] LISP :PROPERTIES: {"orgtrello-id":"521dc9f48e95d74636004107"}
- [X] Emacs-Lisp :PROPERTIES: {"orgtrello-id":"521dc9f7487c2e9b250047a5"}
- [X] Common-Lisp :PROPERTIES: {"orgtrello-id":"521dc9f7ae27842a36003b26"}
- [ ] Scheme :PROPERTIES: {"orgtrello-id":"521dc9f834f52df935003b15"}
- [X] Clojure :PROPERTIES: {"orgtrello-id":"521dc9f9c1b85c905f006b4e"}
- [X] ML :PROPERTIES: {"orgtrello-id":"521dc9f5d49a919614000266"}
- [X] Haskell :PROPERTIES: {"orgtrello-id":"521dc9fa5699f00b25003bd0"}
- [X] Ocaml :PROPERTIES: {"orgtrello-id":"521dc9fb7ef4310554003ab3"}
- [X] Hybrid :PROPERTIES: {"orgtrello-id":"521dc9f6238d072770007217"}
- [X] Scala :PROPERTIES: {"orgtrello-id":"521dc9fc8e95d74636004109"}
Basically, you have 3 levels (cf. possible formats)
- level 1 - Card
- level 2 - Checklist
- level 3 - Item
Steps:
-
Card:
- Place yourself on the
card-identityand hit the bindingC-c o c, this will sync the card (create) in theTODOcolumn in your trello board. - You can edit the label and hit
C-c o cagain, this time, this will sync the card again (update) in trello - Change the status from TODO to any intermediary status, then hit the binding, this will move the card to the list
DOING(depending on your todo keywords list). - Once done, move the status of the card from anything to DONE, hit the binding, this will move the card to the list
DONE.
- Place yourself on the
-
Checklist:
- Place yourself on the checklist
checklist, hit the binding, this will addchecklistas a checklist to your cardcard-identity - Rename your checklist and hit again the binding to update its label.
- Place yourself on the checklist
-
Item:
- Place yourself on your item and hit the binding, this will add the item to such checklist.
- Change the label of the item and hit the binding, this will update its label.
- Change the status of the item to
DONEand hit the binding, this will check such item in trello.
You can use org-mode's deadline, this is mapped to trello's due date notion during the synchronize step.
You can sync all the entities and their arborescence once.
Place yourself on the entity (card or checklist or item) and hit C-c o C.
You can sync all your org-mode file to trello.
Hit C-c o s.
You can sync the content of your trello board into an org-mode file.
Hit C-c o S.
This will update any entries that were already present in the org-mode file and create any entries that were not created yet.
You can remove any entity and its arborescence from the board with C-c o k.
This will also remove the entry from the org-mode buffer.
You can remove all entities from the board C-c o K.
This will also remove the entries from the org-mode buffer.
You can remove all data from the org-mode buffer with C-c o x.
This will remove any org-trello related entries in your file (headers included).
Here are the possible error messages you can get if trying to sync in bad conditions:
- without setting up the consumer-key and the access-token:
- Setup problem - You need to install the consumer-key and the read/write access-token - C-c o i or M-x org-trello/install-board-and-lists-ids
- without setting up the org-mode buffer:
- Setup problem.
Either you did not connect your org-mode buffer with a trello board, to correct this:
* attach to a board through C-c o I or M-x org-trello/install-board-and-lists-ids
* or create a board from scratch with C-c o b or M-x org-trello/create-board).
Either your org-mode's todo keyword list and your trello board lists are not named the same way (which they must).
For this, connect to trello and rename your board's list according to your org-mode's todo list.
Also, you can specify on your org-mode buffer the todo list you want to work with, for example: #+TODO: TODO DOING | DONE FAIL (hit C-c C-c to refresh the setup)
- If the board's list names are different from your org-mode's keyword list:
- Setup problem.
Either you did not connect your org-mode buffer with a trello board, to correct this:
* attach to a board through C-c o I or M-x org-trello/install-board-and-lists-ids
* or create a board from scratch with C-c o b or M-x org-trello/create-board).
Either your org-mode's todo keyword list and your trello board lists are not named the same way (which they must).
For this, connect to trello and rename your board's list according to your org-mode's todo list.
Also, you can specify on your org-mode buffer the todo list you want to work with, for example: #+TODO: TODO DOING | DONE FAIL (hit C-c C-c to refresh the setup)
- no label on the card:
Cannot synchronize the card - missing mandatory label. Skip it...
- no label on the checklist:
Cannot synchronize the checklist - missing mandatory label. Skip it...
- no label on the item:
Cannot synchronize the item - missing mandatory label. Skip it...
- syncing the checklist without syncing the card first:
Cannot synchronize the checklist - the card must synchronized first. Skip it...
- syncing the item without syncing the checklist first:
Cannot synchronize the item - the checklist must be synchronized first. Skip it...
From version 0.1.2 onwards, there is a proxy which is in charge of:
- consuming the synchronization of the entities
- requesting that Trello do other actions too
- proxy admin web page
I also used it to put at your disposal an admin web server - http://localhost:9876/proxy/admin/ - so that you can know which sync actions are running:
- subscribe: Send a mail to emacs.org.trello [AT] librelist.com to subscribe.
- unsubscribe: Send a mail to emacs.org.trello-unsubscribe [AT] librelist.com to unsubscribe.
org-trello is free software under the GPL v3. See the COPYING file for details.