Table of Contents
Understanding the interface
The user interface should be easy to understand. This annotated screenshot shows a query for all documents tagged with Computer, Programming, not Functional Programming of type HTML or HTML document. In this example Ammonite searches the filesystem and the DEVONthink database Computer:
The details view on the right hand side may be shown/hidden by dragging the little knob to the right of the Result Table.
Should the Tag Bar contain more items than can be displayed, its content may be scrolled using the scroll wheel or the two finger swipe gesture.
Right-click on the Tags cloud selector (
) to select what kind of tags you are interested in.
Working with Ammonite
Selecting a Data Source
Ammonite currently supports three Data Sources: Filesystem, DEVONthink databases and Obsidian vaults.
First you have to tell Ammonite which Data Source(s) to search. Select one from the Data Source selector in the upper left of the window. Keeping the ⌥-key pressed while selecting will extend the selection, enabling you to search multiple Data Sources at once.
Note: DEVONthink has to be running in order for Ammonite to be able to collect information about available databases.
Note: An Obsidian vault must have been opened at least once in Obsidian for Ammonite to be able to locate it.
Note: Click the refresh button to the right of the Data Source popup in case Ammonite does not list all Data Sources.
Choosing the right cloud
Below the Data Source selector you find three buttons.
Tags
You can switch between “flat” and “nested” mode by right-clicking this button and selecting the appropriate menu item. When in “flat” mode, the icon will looks like a plain tag (). When in “nested” mode, the icon is a tag with a plus sign (
)
File type 
Choose this Tag Cloud if you want to search documents by their file type.
Timestamp 
Choose this cloud if you want so search documents by their creation- or modification date.
Building a query
To build a query you select tags from the tag cloud. A selected tag will move up to the Tag Bar. Right-Clicking on a tag in the Tag Cloud will add this tag as a “negative” tag to the Tag Bar. Negative tags match items not having this tag applied. Right-clicking a tag in the Tag Bar will change a tag from “positive” to “negative” and vice versa. Left-clicking a tag in the Tag Bar will remove it from the query.
Tags in the Tag Bar can be grouped in Tag Groups to create boolean queries. Tag Groups can be of type ALL (match items having all tags in the group applied), ANY (match items having at least one of the tags in the Tag Group applied) or ONE (matching items having exactly one of the tags in the tag group applied). The Tag Group mode can be changed by clicking on the type indicator at the left and of the Tag Group. A Tag Group can be added by clicking on the + symbol at the right end of a Tag Group. To remove a Tag Group click on the × symbol at the right end of the Tag Group.
In the following sections you will learn how to build queries by example. To follow these examples, you have to replace the tag names, file types and date ranges with data matching your Data Source.
Every document tagged with Language and C/C++
- Start a new query (
⌘⎋) - Click on the subquery type in the Tag Bar until it displays “ALL”
- Left-click on the tag Languages in the Tag Cloud. A green (positive) tag titled Languages will appear in the Tag Bar. The Result Table will immediately be updated to show all documents tagged with “Languages”. The Tag Cloud will be updated to display only tags, which are applied to files tagged with “Languages”.
- Left-click on the tag C/C++ in the Tag Cloud. A green (positive) tag titled C/C++ will appear in the Tag Bar. Again, the Result Table and the Tag Cloud will be updated immediately.
This is it. Your Tag Bar now looks like this: 
Every document tagged with Language but not with C/C++
- Start a new query (
⌘⎋) - Click on the subquery type in the Tag Bar until it displays “ALL”
- Left-click on the tag Languages in the Tag Cloud. A green (positive) tag titled Languages will appear in the Tag Bar. The Result Table will immediately be updated to show all documents tagged with Languages. The Tag Cloud will be updated to display only tags, which are applied to files tagged with Languages.
- Right-click on the tag C/C++ in the Tag Cloud. A red (negative) tag titled C/C++ will appear in the Tag Bar. Again, the Result Table and the Tag Cloud will be updated immediately.
This is it. Your Tag Bar now looks like this: 
Every document tagged with Language of type PDF+Text or HTML
- Start a new query (
⌘⎋) - Click on the subquery type in the Tag Bar until it displays “ALL”
- Left-click on the tag Languages in the Tag Cloud. A green (positive) tag titled Languages will appear in the Tag Bar. The Result Table will immediately be updated to show all documents tagged with Languages. The Tag Cloud will be updated to display only tags, which are applied to files tagged with Languages.
- Click on the Filetypes tab of the Tag Cloud.
- Add a new subquery by left-clicking the little plus sign in the upper right corder of the Tag Bar
- Make sure the new subquery is of type “ANY” Left-click on the tag PDF+Text in the Tag Cloud. A green (positive) tag titled “PDF+Text” will appear inside the new tag group. Again, the Result Table and the Tag Cloud will be updated immediately.
- Left-click on the tag HTML in the Tag Cloud. A green (positive) tag titled “HTML” will appear inside the new tag group. Once more, the Result Table and the Tag Cloud will be updated immediately.
This is it. Your Tag Bar now looks like this: 
Every document created in the year 2010 or between Sept 2nd 2009 and December 31st 2009
- Start a new query (
⌘⎋) - Click on the subquery type in the Tag Bar until it displays
ANY - Click on the Dates tab of the Tag Cloud
- Click on the
Createdradio button if it is not selected already - Left-click on 2010 in the Tag Cloud. A green (positive) tag titled 2010 will appear in the Tag Bar. The Result Table will immediately be updated to show all documents created in 2010. The Tag Cloud will be updated to display any month in 2010 in which documents have been created
- We want the complete year 2010, so we click the
Donebutton. The Tag Cloud is updated and displays every year in which documents have been created, save the one we’ve selected before. - Left-click on 2009 in the Tag Cloud. A green (positive) tag titled 2009 will appear in the Tag Bar. The Result Table will now contain every document created in 2010 or 2009. The Tag Cloud is updated and displays every month in 2009, in which documents have been created.
- Left-click on 09 in the Tag Cloud. Our green 2009 tag in the Tag Bar now becomes 09/2009. The Result Table will now contain every document created in 2010 or September 2009. The Tag Cloud is updated and displays every day in September 2009, on which documents have been created.
- Left-click on 02 in the Tag Cloud. Our green 09/2009 tag in the Tag Bar now becomes 02.09.2009. The Result Table will now contain every document created in 2010 or on September 2nd 2009. The Tag Cloud is updated and displays every year from 2009 on, in which documents have been created.
- Left-click on 2009 in the Tag Cloud. Our green 02.09.2009 tag in the Tag Bar now becomes 02.09.2009 - 31.12.2009. The Result Table will now contain every document created in 2010 or Q3 2009. The Tag Cloud is updated and displays every month of 2009 from 09 on, in which documents have been created.
- As this is exactly what we want, we click the
Donebutton.
This is it. Your Tag Bar now looks like this: 
Nested Tags
What are nested Tags
Nested tags are a convention. Simply add context(s) as prefixes to the actual tag. No special software is required to read or write them.
Suppose you have a collection of ebooks. You could add a tag for the publisher, the publishing date and the usual keywords concerning the actual content. You could end up with these Tags:
- eBook
- Addison-Wesley
- 2002
- Programming
- C
Alternatively you can provide a context for your tags:
- eBook>Publisher>Addison-Wesley
- eBook>Published>2002
- Programming
- C
Ammonite will display the tags Programming and C as usual. These tags are considered “flat”. The publishing related information is displayed in two specific clouds, Publisher and Published.
There is a configuration option Display nested tags in flat Tag Cloud in the General tab of the Ammonite Settings. Switching this option on will add the highest level of a nested tag (
C for A>B>C) to the flat tag cloud. Should a flat tag with the same name exist, the tag will show up twice.
When the preferences option Display components of nested tags in flat Tag Cloud is enabled all components of the hierarchy will be added to the flat tag cloud (
A and B in addition to C). Use these container tags to query for items sharing the same container.
Hovering the mouse pointer over a tag will bring up a tooltip displaying the full tag name.
There is no limit to how deep tags may be nested.
Note: Obsidian uses the / character to build nested tags. Keep this in mind when creating nested tags in Obsidian.
Automatic generation of nested tags
Use the preferences option “Create nested tags from location” in the DEVONthink or Obsidian section to automatically create nested tags from a record’s location in a DEVONthink database or Obsidian vault. For a record located in /eBook/Publisher/Addison-Wesley Ammonite will generate the nested tag eBook>Publisher>Addison-Wesley. This is useful for databases which have “Exclude Groups from Tagging” enabled.
Keyboard shortcuts
This manual uses special symbols to refer to special keys. The table below explains them.
| Key symbol | Description |
|---|---|
| ⎋ | Escape |
| ⌃ | Control |
| ⌥ | Option or Alt |
| ⌘ | Command or |
| ⇧ | Shift |
| ⏎ | Return or Enter |
| ↹ | Tab |
| ↖ ↘ | Home and End |
| ⇞ ⇟ | Page up and page down |
| ↑ ↓ ← → | Arrows |
| ⌫ | Backspace |
| ⌦ | Delete |
Regardless of focus
| Key symbol | Description |
|---|---|
| ↹ | Switch input focus to next available element:
|
| ⌘⎋ | Clear Tag Bar |
| ⌘= | Include documents tagged with tag below Tag Cloud cursor in search result |
| ⌘- | Exclude documents tagged with tag below Tag Cloud cursor from search result |
| ⌘1 | Icon View |
| ⌘2 | List View |
| ⌘⌥1 | Show Tag Cloud; focus on search field |
| ⌘⌥2 | Show file type cloud; focus on search field |
| ⌘⌥3 | Show date cloud |
| ⌘I | Open info panel of Finder or DEVONthink (depending on selected document) |
| ⌘R | Reveal selected document in DEVONthink (Only for documents in DEVONthink database) |
| ⌘⇧R | Reveal selected document in Finder |
| ⌘O | Open selected documents |
| ⌘⇧O | Open selected documents in their default application |
| ⌘⇞ | Show previous page of selected PDF in Preview Panel |
| ⌘⇟ | Show next page of selected PDF in Preview Panel |
| ⌘↖ | Show first page of selected PDF in Preview Panel |
| ⌘↘ | Show last page of selected PDF in Preview Panel |
| ⌘⌥R | Replicate result set to a DEVONthink group (Only for documents in DEVONthink database) |
| ⌘⇧F | Show Result Filter. The Result Filter will be displayed right above the Result Table. It allows you to filter the Result Table by name. |
Focus on Tag Filter
| Key symbol | Description |
|---|---|
| ⎋ (w/ content) | Reset filter |
| ⎋ (w/o content) | Remove last tag/subquery from currently active subquery in Tag Bar |
| ⎋ (w/o content, empty Tag Bar) | Close search window |
| ⏎ | Focus on Tag Cloud |
Focus on Result Filter
| Key symbol | Description |
|---|---|
| ⎋ (w/ content) | Reset filter |
| ⎋ (w/o content) | Switch input focus to Tag Cloud Filter |
| ⏎ | Focus on Result Table |
Focus on Tag Cloud
| Key symbol | Description |
|---|---|
| ⎋ | Switch input focus to Tag Cloud Filter |
| ←→↑↓ | Move cursor |
| ⏎ | Include documents tagged with tag below Tag Cloud cursor in search result |
| ⇧⏎ | Exclude documents tagged with tag below Tag Cloud cursor from search result |
| Any key | Move cursor to tag beginning with key |
Focus on Result Table
| Key symbol | Description |
|---|---|
| ⎋ | Switch input focus to Tag Cloud Filter |
| ↑ or ↓ | Select previous/next item in result set |
| ← or → | Select first/last item in result set |
| ␣ | Preview selected items with QuickLook |
The Cache
When Ammonite searches a Data Source for the first time, it automatically creates a cache, which allows it to perform future searches instantaneously. Whenever you modify a Data Source (add, remove, move or rename a document or tag), you should update Ammonite’s cache by selecting the menu item ‘Rescan current Data Source’ (⌥⌘S).
Saving/Loading/Deleting Searches
Ammonite allows you to save often used queries.
Saving Queries
Right-click (or ⌘-click) on the tag bar (not on a tag; this would just negate it) to open the popup menu for saved searches. Select Save. Enter a name for the search in the upcoming panel.
Loading Queries
Right-click (or ⌘-click) on the tag bar (not on a tag; this would just negate it) to open the popup menu for saved searches. Select the saved search you’d like to load.
Deleting a Query
Right-click (or ⌘-click) on the tag bar (not on a tag; this would just negate it) to open the popup menu for saved searches. Select the saved search you’d like to delete. Bring up the popup menu again. Select Delete Query.
Troubleshooting
Problems indexing a DEVONthink database
Sometimes Ammonite is unable to obtain all required information about an item in a DEVONthink database. Usually this happens when DEVONthink failed to store some meta data (like Kind, Size, Created, …) for this item.
If Ammonite encounters one or more items like the in a DEVONthink database while indexing it will offer you to replicate said items to the folder /Ammonite-Debug. Check every item in this folder. Can it be opened? Has it missing meta data? You may want to drag those items out of DEVONthink onto a Finder window to export them. Delete the replicas and the originals in DEVONthink, then re-import the previously exported items. Check if they now can be opened in DEVONthink and if they have all meta data. If the items are now ok you can start indexing with Ammonite again. If re-importing them does not solve the issue please remove them from the database. Ammonite won’t be able to index the database while it contains these items. You may want to contact DEVONthink support and ask why they cannot be porperly imported.