97 lines
5.4 KiB
Markdown
97 lines
5.4 KiB
Markdown
# YKanBan Usage
|
||
|
||
YKanBan is a local/offline kanban board. It works like Git in one respect: all data for a managed project lives in a `.ykanban` folder at the project root, so the board travels with the project folder.
|
||
|
||
## 1. Workspace
|
||
|
||
- A **workspace** is a folder that directly contains a `.ykanban` directory. Only the given folder is checked; parent folders are never searched.
|
||
- `.ykanban` contains `ykanban.db` (the SQLite database with the board, cards and tags) and `ykanban.lock` (the exclusive lock file).
|
||
- A workspace is opened by exactly one YKanBan instance at a time. Opening the same workspace a second time shows the lock-conflict page.
|
||
|
||
### Command line
|
||
|
||
```
|
||
ykanban <path>
|
||
```
|
||
|
||
- `<path>` is the workspace folder to open. A relative path is resolved against the current working directory.
|
||
- Exactly one argument is required. Starting without arguments, with more than one argument, with a blank argument, with an argument starting with `-` (any option form, `--help` included), or with a path that does not exist or is not a folder shows the argument error page.
|
||
- If the folder exists but has no `.ykanban`, the not-initialized page is shown with an **Initialize Workspace** button. Initializing creates the database and seeds the preset columns and tags in the current interface language.
|
||
|
||
## 2. Do not commit `.ykanban` to Git
|
||
|
||
`.ykanban` holds machine-local state and a lock file; it should not be committed. Add it to your **global** gitignore so it is ignored in every repository:
|
||
|
||
```
|
||
# ~/.gitignore_global (or %USERPROFILE%\.gitignore_global on Windows)
|
||
.ykanban/
|
||
```
|
||
|
||
Then enable the global ignore file once:
|
||
|
||
```
|
||
git config --global core.excludesFile ~/.gitignore_global
|
||
```
|
||
|
||
## 3. Backing up and migrating a workspace
|
||
|
||
The database runs in SQLite WAL mode. A workspace is therefore **three files**, not one: `ykanban.db`, `ykanban.db-wal` and `ykanban.db-shm`.
|
||
|
||
To back up or move a workspace, copy **all three files together** while YKanBan is closed. Copying only `ykanban.db` can lose the most recent changes.
|
||
|
||
## 4. Search syntax
|
||
|
||
The board search runs only when you press the search button (or press Enter in the search box); there is no live search. A blank query shows everything. The clear button (×) empties the box and restores the full board.
|
||
|
||
Search keywords (`AND`, `OR`) and qualifier keys are fixed English grammar and are **never localized**.
|
||
|
||
### 4.1 Grammar
|
||
|
||
```
|
||
query := orExpr
|
||
orExpr := andExpr ( OR andExpr )*
|
||
andExpr := operand ( (AND)? operand )* // adjacent terms are an implicit AND
|
||
operand := atom | '(' orExpr ')'
|
||
atom := word | phrase | qualifier
|
||
qualifier := key ':' (word | phrase)
|
||
key := tag | title | content | id | column
|
||
phrase := '"' any text '"' // escapes: \" to literal quote and \\ to literal backslash
|
||
```
|
||
|
||
### 4.2 Semantics
|
||
|
||
- `AND` (explicit or by adjacency) binds tighter than `OR`; parentheses force grouping.
|
||
- Only uppercase `AND` / `OR` are operators. Lowercase `and` / `or` are plain words. To search for the literal words `AND` or `OR`, quote them, for example `"AND"`.
|
||
- A bare word or phrase matches a **substring of the title OR the content**.
|
||
- `tag:NAME` matches a tag by its **exact** name.
|
||
- `column:TITLE` matches a column by its **exact** title.
|
||
- `title:TEXT` matches a substring of the card title, and `content:TEXT` matches a substring of the card content.
|
||
- `id:N` matches a card by its **exact** positive integer id; an optional leading `#` is allowed (`id:#61`).
|
||
- All matching is Unicode case-insensitive (both sides are case-folded before comparing).
|
||
- Quotes allow values with spaces, for example `tag:"release notes"` or `column:"In Progress"`.
|
||
- Inside a phrase, `\"` produces a literal quote and `\\` a literal backslash.
|
||
|
||
### 4.3 Strict validation
|
||
|
||
An invalid expression opens a modal error dialog and **does not run the search**. The error dialog is centered on the parent window; its text is a localized "query expression is invalid" message plus the parser's non-localized English detail. After closing it, the search box keeps what you typed and the board keeps the previous results.
|
||
|
||
The following are invalid:
|
||
|
||
- unbalanced parentheses, for example `(a` or `a)`;
|
||
- a dangling operator, for example `bug AND`;
|
||
- consecutive operators, for example `a AND OR b`;
|
||
- a qualifier without a value, for example `tag:`;
|
||
- a qualifier phrase separated from its key by whitespace, for example `tag: "x"` (write `tag:"x"` instead);
|
||
- an unterminated phrase, for example `"abc`;
|
||
- an empty phrase, for example `""`;
|
||
- a phrase glued to other text, for example `a"b"`;
|
||
- an invalid escape inside a phrase (a backslash not followed by `"` or `\`), for example `tag:"a\x"`;
|
||
- a bare backslash in a word, for example `a\b`;
|
||
- an unquoted qualifier value containing `:` or equal to `AND`/`OR`, for example `tag:a:b` (quote the value instead);
|
||
- an id value that is not an unquoted positive integer with an optional `#`, for example `id:0`, `id:-1` or `id:"1"`;
|
||
- an unknown qualifier key. Only `tag`, `title`, `content`, `id` and `column` are valid, and the key is case-sensitive, so `Tag:x` is an error. A colon not preceded by a valid key (for example `:foo` or `http://x`) is an error; quote such text to search for it literally.
|
||
|
||
## 5. Export
|
||
|
||
The **Export** button writes a human-readable Markdown snapshot of the whole board (columns, cards and the tag table) to a file you choose. The suggested file name and the timestamps in the document follow the current interface language. The export is read-only; there is no import.
|