na 1.2.5 → 1.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 145c2efb28f23a047dced5bad341aa9339ff437fd4f31faeb44923fdc5d6af0c
-  data.tar.gz: b16951edb2e2753c8c1a83a52b1650db7770a4d6ac2615aa4995e37bdcf20a02
+  metadata.gz: 77270e07e7c7d4332a5fb8ec87f4e9ad5496bd220d188e75adfb71026aff1180
+  data.tar.gz: a3521feaefc9573bd78344b6a16ae57719284bde611e8f9f6e664238fcc1b5c3
 SHA512:
-  metadata.gz: e790052ffdabf6ee749f545d4dade110a45167174700fc3f351d4e688b870c8b7bebf063678232613c12d1e3db3f0bc4491f12a01eededd0c8fd0d8710cfc63c
-  data.tar.gz: c433b14e48f7ee09ca8a3a27a305b67e21087e0230a16d6f75c1b9d404e46ee5f120a8411f1f1d139b6e36512ac866ad5edc0ca2f29530b7b990baf0da776b16
+  metadata.gz: 2a714a764879036b9ad51626445e9ef920909da333e3fc6ecb18b8b3755cf8afad811c7baf1e3aea622a5d74b1ca41e1cf64c43541f772db9ae50cfc03c1de90
+  data.tar.gz: 06b865817db9731ded06c415f5c71a10a2f8b928b0f6da5ee9cca083f951e35ee716eaf6e2558daf89ec5378910286be4304fbdbe67e17756eae2be553fee0ea

data/CHANGELOG.md

@@ -1,3 +1,39 @@
+### 1.2.7
+
+2022-10-28 07:29
+
+#### IMPROVED
+
+- Code refactoring
+
+#### FIXED
+
+- All_req error
+- Adding entries to project names containing hyphen
+
+### 1.2.6
+
+2022-10-26 10:50
+
+#### NEW
+
+- Pass notes to STDIN using piped input when using the `--note` switch
+- `--notes` switch for next, find, and tagged to include action notes in output
+
+#### IMPROVED
+
+- Update na saved examples and documentation
+- Better handling of unknown commands, affecting `na -a ACTION` and `na SAVED_SEARCH`
+- Additional help documentation and examples
+- Updated documentation
+- If a todo query contains only a negative, display all non-matching todos
+- Don't display readline prompts if not a TTY
+- Prompt hook generator recognizes when a global file is being used and modifies prompt hooks to search for project name or tag based on the value of `--cwd_as`.
+
+#### FIXED
+
+- Debug messages showing when not using --debug
+
 ### 1.2.5
 
 2022-10-26 07:39

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    na (1.2.5)
+    na (1.2.7)
       chronic (~> 0.10, >= 0.10.2)
       gli (~> 2.21.0)
       mdless (~> 1.0, >= 1.0.32)

data/README.md

@@ -9,12 +9,12 @@
 _If you're one of the rare people like me who find this useful, feel free to
 [buy me some coffee][donate]._
 
-The current version of `na` is 1.2.5
+The current version of `na` is 1.2.7
 .
 
 `na` ("next action") is a command line tool designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-formatted files (but any plain text format will do), looking for `@na` tags (or whatever you specify) in todo files in your current folder. 
 
-Used with Taskpaper files, it can add new todo items quickly from the command line, automatically tagging them as next actions.
+Used with Taskpaper files, it can add new action items quickly from the command line, automatically tagging them as next actions. It can also mark actions as completed, delete them, archive them, and move them between projects.
 
 It can also auto-display next actions when you enter a project directory, automatically locating any todo files and listing their next actions when you `cd` to the project (optionally recursive). See the [Prompt Hooks](#prompt-hooks) section for details.
 
@@ -31,9 +31,13 @@ If you don't have Ruby/RubyGems, you can install them pretty easily with Homebre
 
 
 
+### Optional Dependencies
+
+If you have [gum][] installed, na will use it for command line input when adding tasks and notes. If you have [fzf][] installed, it will be used for menus, falling back to gum if available.
+
 ### Features
 
-You can list next actions in files in the current directory by typing `na`. By default, `na` looks for `*.taskpaper` files and extracts items tagged `@na` and not `@done`. All of these can be changed in the configuration.
+You can list next actions in files in the current directory by typing `na`. By default, `na` looks for `*.taskpaper` files and extracts items tagged `@na` and not `@done`. This can be modified to work with a single global file, and all of these options can be changed in the configuration.
 
 #### Easy matching
 
@@ -53,6 +57,16 @@ If found, it will try to locate an `Inbox:` project, or create one if it doesn't
 
 You can mark todos as complete, delete them, add and remove tags, change priority, and even move them between projects with the `na update` command.
 
+### Terminology
+
+**Todo**: Refers to a todo file, usually a TaskPaper document
+
+**Project**: Refers to a project within the TaskPaper document, specified by an alphanumeric name (spaces allowed) followed by a colon. Projects can be nested by indenting a tab beyond the parent projects indentation.
+
+**Action**: Refers to an individual task, specified by a line starting with a hyphen (`-`)
+
+**Note**: Refers to lines appearing between action lines that start without hyphens. The note is attached to the preceding action regardless of indentation.
+
 ### Usage
 
 ```
@@ -63,7 +77,7 @@ SYNOPSIS
     na [global options] command [command options] [arguments...]
 
 VERSION
-    1.2.5
+    1.2.7
 
 GLOBAL OPTIONS
     -a, --[no-]add          - Add a next action (deprecated, for backwards compatibility)
@@ -105,6 +119,12 @@ Example: `na add This feature @idea I have`
 
 If you run the `add` command with no arguments, you'll be asked for input on the command line.
 
+###### Adding notes
+
+Use the `--note` switch to add a note. If STDIN (piped) input is present when this switch is used, it will be included in the note. A prompt will be displayed for adding additional notes, which will be appended to any STDIN note passed. Press CTRL-d to end editing and save the note. 
+
+Notes are not displayed by the `next/tagged/find` commands unless `--notes` is specified.
+
 ```
 NAME
     add - Add a new next action
@@ -122,7 +142,7 @@ COMMAND OPTIONS
     -f, --file=PATH                 - Specify the file to which the task should be added (default: none)
     --finish, --done                - Mark task as @done with date
     --in, --todo=TODO_FILE          - Add to a known todo file, partial matches allowed (default: none)
-    -n, --note                      - Prompt for additional notes
+    -n, --note                      - Prompt for additional notes. STDIN input (piped) will be treated as a note if present.
     -p, --priority=PRIO             - Add a priority level 1-5 (default: 0)
     -t, --tag=TAG                   - Use a tag other than the default next action tag (default: none)
     --to, --project, --proj=PROJECT - Add action to specific project (default: Inbox)
@@ -133,7 +153,7 @@ EXAMPLES
     # Add a new action to the Inbox, including a tag
     na add "A cool feature I thought of @idea"
 
-    # Add a new action to the Inbox, set its @priority to 4, and prompt for an additional note
+    # Add a new action to the Inbox, set its @priority to 4, and prompt for an additional note.
     na add "A bug I need to fix" -p 4 -n
 
     # A parenthetical at the end of an action is interpreted as a note
@@ -190,6 +210,7 @@ COMMAND OPTIONS
     --[no-]done                            - Include @done actions
     -e, --regex                            - Interpret search pattern as regular expression
     --in=TODO_PATH                         - Show actions from a specific todo file in history. May use wildcards (* and ?) (default: none)
+    --[no-]notes                           - Include notes in output
     -o, --or                               - Combine search tokens with OR, displaying actions matching ANY of the terms
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
     --save=TITLE                           - Save this search for future use (default: none)
@@ -232,6 +253,8 @@ Examples:
 - `na next -d 3` (list all next actions in the current directory and look for additional files 3 levels deep from there)
 - `na next marked2` (show next actions from another directory you've previously used na on)
 
+To see all next actions across all known todos, use `na next "*"`. You can combine multiple arguments to see actions across multiple todos, e.g. `na next marked nvultra`.
+
 ```
 NAME
     next - Show next actions
@@ -247,6 +270,7 @@ COMMAND OPTIONS
     -d, --depth=DEPTH                      - Recurse to depth (default: none)
     --[no-]done                            - Include @done actions
     --in, --todo=TODO_FILE                 - Display matches from a known todo file (may be used more than once, default: none)
+    --[no-]notes                           - Include notes in output
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
     -t, --tag=TAG                          - Alternate tag to search for (default: none)
 
@@ -290,6 +314,9 @@ Search names can be partially matched when calling them, so if you have a search
 
 Run `na saved` without an argument to list your saved searches.
 
+> As a shortcut, if `na` is run with one argument that matches the name of a saved search, it will execute that search, so running `na maybe` is the same as running `na saved maybe`.
+
+
 ```
 NAME
     saved - Execute a saved search
@@ -307,9 +334,13 @@ COMMAND OPTIONS
 
 EXAMPLES
 
-    na saved overdue
+    na tagged "+maybe,+priority<=3" --save maybelater
+
+    na saved maybelater
 
-    na saved over
+    na saved maybe
+
+    na maybe
 
     na saved
 ```
@@ -339,6 +370,7 @@ COMMAND OPTIONS
     -d, --depth=DEPTH                      - Recurse to depth (default: none)
     --[no-]done                            - Include @done actions
     --in, --todo=TODO_FILE                 - Display matches from a known todo file (may be used more than once, default: none)
+    --[no-]notes                           - Include notes in output
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
     -t, --tag=TAG                          - Alternate tag to search for (default: none)
 
@@ -382,11 +414,27 @@ You can specify a particular todo file using `--file PATH` or any todo from hist
 
 If more than one file is matched, a menu will be presented, multiple selections allowed. If multiple actions match the search within the selected file(s), a menu will be presented. If you have fzf installed, you can select one action to update with return, or use tab to mark multiple tasks to which the action will be applied. With gum you can use j, k, and x to mark multiple actions. Use the `--all` switch to force operation on all matched tasks, skipping the menu.
 
-Any time an update action is carried out, a backup of the file before modification will be made in the same directory with a `.` prepended and `.bak` appended (e.g. `marked.taskpaper` is copied to `.marked.taskpaper.bak`). Only one undo step is available, but if something goes wrong (and this feature is still experimental, so be wary), you can just copy the "~" file back to the original.
+Any time an update action is carried out, a backup of the file before modification will be made in the same directory with a `.` prepended and `.bak` appended (e.g. `marked.taskpaper` is copied to `.marked.taskpaper.bak`). Only one undo step is available, but if something goes wrong (and this feature is still experimental, so be wary), you can just copy the ".bak" file back to the original.
+
+###### Marking a task as complete
+
+You can mark an action complete using `--finish`, which will add a dated @done tag to the action. You can also mark it @done and immediately move it to the Archive project using `--archive`.
+
+If you just want the action to stop appearing as a "next action," you can remove the next action tag using `--remove na` (or whatever your next action tag is configured as).
+
+If you want to permanently delete an action, use `--delete` to remove it entirely.
+
+###### Moving between projects
 
 You can specify a new project for an action (moving it) with `--proj PROJECT_PATH`. A project path is hierarchical, with each level separated by a colon or slash. If the project path provided roughly matches an existing project, e.g. "mark:bug" would match "Marked:Bugs", then that project will be used. If no match is found, na will offer to generate a new project/hierarchy for the path provided. Strings will be exact but the first letter will be uppercased.
 
-See the help output for a list of available actions.
+###### Adding notes
+
+Use the `--note` switch to add a note. If STDIN (piped) input is present when this switch is used, it will be included in the note. A prompt will be displayed for adding additional notes, which will be appended to any STDIN note passed. Press CTRL-d to end editing and save the note.
+
+Notes are not displayed by the `next/tagged/find` commands unless `--notes` is specified.
+
+See the help output for a list of all available actions.
 
 ```
 NAME
@@ -410,7 +458,7 @@ COMMAND OPTIONS
     -f, --finish                    - Add a @done tag to action
     --file=PATH                     - Specify the file to search for the task (default: none)
     --in, --todo=TODO_FILE          - Use a known todo file, partial matches allowed (default: none)
-    -n, --note                      - Prompt for additional notes. Input will be appended to any existing note.
+    -n, --note                      - Prompt for additional notes. Input will be appended to any existing note.     If STDIN input (piped) is detected, it will be used as a note.
     -o, --overwrite                 - Overwrite note instead of appending
     -p, --priority=PRIO             - Add/change a priority level 1-5 (default: 0)
     -r, --remove=TAG                - Remove a tag to the action (may be used more than once, default: none)
@@ -435,6 +483,9 @@ EXAMPLES
 
 Global options such as todo extension and default next action tag can be stored permanently by using the `na initconfig` command. Run na with the global options you'd like to set, and add `initconfig` at the end of the command. A file will be written to `~/.na.rc`. You can edit this manually, or just update it using the `initconfig --force` command to overwrite it with new settings.
 
+> You can see all available global options by running `na help`.
+
+
 Example: `na --ext md --na_tag next initconfig --force`
 
 When this command is run, it doesn't include options for subcommands, but inserts placeholders for them. If you want to permanently set an option for a subcommand, you'll need to edit `~/.na.rc`. For example, if you wanted the `next` command to always recurse 2 levels deep, you could edit it to look like this:
@@ -465,12 +516,14 @@ When using a global file, you can additionally include `--cwd_as TYPE` to determ
 
 #### Add tasks at the end of a project
 
-By default, tasks are added at the top of the target project (Inbox, etc.). If you prefer new tasks to go at the bottom by default, include `--add_at end` as a global option when running `initconfig`.
+By default, tasks are added at the top of the target project (Inbox, etc.). If you prefer new tasks to go at the end of the project by default, include `--add_at end` as a global option when running `initconfig`.
 
 ### Prompt Hooks
 
 You can add a prompt command to your shell to have na automatically list your next actions when you `cd` into a directory. To install a prompt command for your current shell, just run `na prompt install`. It works with Zsh, Bash, and Fish. If you'd rather make the changes to your startup file yourself, run `na prompt show` to get the hook and instructions printed out for copying.
 
+If you're using a single global file, you'll need `--cwd_as` to be `tag` or `project` for a prompt command to work. na will detect which system you're using and provide a prompt command that lists actions based on the current directory using either project or tag.
+
 > You can also get output for shells other than the one you're currently using by adding "bash", "zsh", or "fish" to the show or install command.
 
 
@@ -479,9 +532,6 @@ You can add a prompt command to your shell to have na automatically list your ne
 
 After installing a hook, you'll need to close your terminal and start a new session to initialize the new commands.
 
-### Misc
-
-If you have [gum][] installed, na will use it for command line input when adding tasks and notes. If you have [fzf][] installed, it will be used for menus, falling back to gum if available.
 
 [fzf]: https://github.com/junegunn/fzf
 [gum]: https://github.com/charmbracelet/gum

data/bin/na

@@ -4,6 +4,7 @@
 $LOAD_PATH.unshift File.join(__dir__, '..', 'lib')
 require 'gli'
 require 'na'
+require 'fcntl'
 
 # Main application
 class App
@@ -63,7 +64,7 @@ class App
   flag %i[d depth], type: :integer, must_match: /^[1-9]$/
 
   desc 'Display verbose output'
-  switch %i[debug]
+  switch %i[debug], default_value: false
 
   desc 'Show next actions'
   long_desc 'Next actions are actions which contain the next action tag (default @na),
@@ -94,6 +95,9 @@ class App
     c.arg_name 'PROJECT[/SUBPROJECT]'
     c.flag %i[proj project]
 
+    c.desc 'Include notes in output'
+    c.switch %i[notes], negatable: true, default_value: false
+
     c.desc 'Include @done actions'
     c.switch %i[done]
 
@@ -102,8 +106,8 @@ class App
         cmd = ['add']
         cmd.push('--note') if global_options[:note]
         cmd.concat(['--priority', global_options[:priority]]) if global_options[:priority]
-        cmd.push(ARGV.unshift(NA.command_line[0])) if NA.command_line.count > 1
-
+        cmd.push(NA.command_line) if NA.command_line.count > 1
+        cmd.unshift(*NA.globals)
         exit run(cmd)
       end
 
@@ -141,7 +145,7 @@ class App
                                          project: options[:project],
                                          require_na: require_na)
 
-      NA.output_actions(actions, depth, files: files)
+      NA.output_actions(actions, depth, files: files, notes: options[:notes])
     end
   end
 
@@ -156,11 +160,11 @@ class App
   command :add do |c|
     c.example 'na add "A cool feature I thought of @idea"', desc: 'Add a new action to the Inbox, including a tag'
     c.example 'na add "A bug I need to fix" -p 4 -n',
-              desc: 'Add a new action to the Inbox, set its @priority to 4, and prompt for an additional note'
+              desc: 'Add a new action to the Inbox, set its @priority to 4, and prompt for an additional note.'
     c.example 'na add "An action item (with a note)"',
               desc: 'A parenthetical at the end of an action is interpreted as a note'
 
-    c.desc 'Prompt for additional notes'
+    c.desc 'Prompt for additional notes. STDIN input (piped) will be treated as a note if present.'
     c.switch %i[n note], negatable: false
 
     c.desc 'Add a priority level 1-5'
@@ -205,9 +209,8 @@ class App
       if NA.global_file
         target = File.expand_path(NA.global_file)
         unless File.exist?(target)
-          print NA::Color.template('{by}Specified file not found, create it? {w}(y/{g}N{w}){x} ')
-          res = reader.read_char
-          if res =~ /y/i
+          res = NA.yn(NA::Color.template('{by}Specified file not found, create it'), default: true)
+          if res
             basename = File.basename(target, ".#{NA.extension}")
             NA.create_todo(target, basename)
           else
@@ -218,9 +221,8 @@ class App
       elsif options[:file]
         target = File.expand_path(options[:file])
         unless File.exist?(target)
-          print NA::Color.template('{by}Specified file not found, create it? {w}(y/{g}N{w}){x} ')
-          res = reader.read_char
-          if res =~ /y/i
+          res = NA.yn(NA::Color.template('{by}Specified file not found, create it'), default: true)
+          if res
             basename = File.basename(target, ".#{NA.extension}")
             NA.create_todo(target, basename)
           else
@@ -230,11 +232,13 @@ class App
         end
       elsif options[:todo]
         todo = []
+        all_req = options[:todo] !~ /[+!\-]/
         options[:todo].split(/ *, */).each do |a|
-          m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+          m = a.match(/^(?<req>[+\-!])?(?<tok>.*?)$/)
           todo.push({
                       token: m['tok'],
-                      required: !m['req'].nil?
+                      required: all_req || (!m['req'].nil? && m['req'] == '+'),
+                      negate: !m['req'].nil? && m['req'] =~ /[!\-]/
                     })
         end
         dirs = NA.match_working_dir(todo)
@@ -246,22 +250,18 @@ class App
           unless File.exist?(target)
 
             res = NA.yn(NA::Color.template("{by}Specified file not found, create #{todo}"), default: true)
-            if res
-              basename = File.basename(target, ".#{NA.extension}")
-              NA.create_todo(target, basename)
-            else
-              NA.notify('{r}Cancelled{x}', exit_code: 1)
+            NA.notify('{r}Cancelled{x}', exit_code: 1) unless res
 
-            end
+            basename = File.basename(target, ".#{NA.extension}")
+            NA.create_todo(target, basename)
           end
 
         end
       else
         files = NA.find_files(depth: options[:depth])
         if files.count.zero?
-          print NA::Color.template('{by}No todo file found, create one? {w}(y/{g}N{w}){x} ')
-          res = reader.read_char
-          if res =~ /y/i
+          res = NA.yn(NA::Color.template('{by}No todo file found, create one'), default: true)
+          if res
             basename = File.expand_path('.').split('/').last
             target = "#{basename}.#{NA.extension}"
             NA.create_todo(target, basename)
@@ -269,17 +269,15 @@ class App
           end
         end
         target = files.count > 1 ? NA.select_file(files) : files[0]
-        unless files.count.positive? && File.exist?(target)
-          NA.notify('{r}Cancelled{x}', exit_code: 1)
+        NA.notify('{r}Cancelled{x}', exit_code: 1) unless files.count.positive? && File.exist?(target)
 
-        end
       end
 
       action = if args.count.positive?
                  args.join(' ').strip
-               elsif TTY::Which.exist?('gum')
+               elsif $stdin.isatty && TTY::Which.exist?('gum')
                  `gum input --placeholder "Enter a task" --char-limit=500 --width=#{TTY::Screen.columns}`.strip
-               else
+               elsif $stdin.isatty
                  puts NA::Color.template('{bm}Enter task:{x}')
                  reader.read_line(NA::Color.template('{by}> {bw}')).strip
                end
@@ -310,9 +308,12 @@ class App
 
       action = "#{action.gsub(/#{na_tag}\b/, '')}#{na_tag}"
 
-      line_note = if options[:note]
+      stdin_note = NA.stdin ? NA.stdin.split("\n") : []
+
+      line_note = if options[:note] && $stdin.isatty
+                    puts stdin_note unless stdin_note.nil?
                     if TTY::Which.exist?('gum')
-                      args = ['--placeholder "Enter a note, CTRL-d to save"']
+                      args = ['--placeholder "Enter additional note, CTRL-d to save"']
                       args << '--char-limit 0'
                       args << '--width $(tput cols)'
                       `gum write #{args.join(' ')}`.strip.split("\n")
@@ -322,9 +323,9 @@ class App
                     end
                   end
 
-      note = split_note.nil? ? [] : [split_note]
+      note = stdin_note.empty? ? [] : stdin_note
+      note.concat(split_note) unless split_note.nil?
       note.concat(line_note) unless line_note.nil?
-      note = [] if note.empty?
 
       NA.add_action(target, options[:project], action, note, finish: options[:finish], append: append)
     end
@@ -337,12 +338,15 @@ class App
   allow you to pick which file to act on.'
   arg_name 'ACTION'
   command %i[update] do |c|
-    c.example 'na update --remove na "An existing task"', desc: 'Find "An existing task" action and remove the @na tag from it'
+    c.example 'na update --remove na "An existing task"',
+              desc: 'Find "An existing task" action and remove the @na tag from it'
     c.example 'na update --tag waiting "A bug I need to fix" -p 4 -n',
               desc: 'Find "A bug..." action, add @waiting, add/update @priority(4), and prompt for an additional note'
-    c.example 'na update --archive My cool action', desc: 'Add @done to "My cool action" and immediately move to Archive'
+    c.example 'na update --archive My cool action',
+              desc: 'Add @done to "My cool action" and immediately move to Archive'
 
-    c.desc 'Prompt for additional notes. Input will be appended to any existing note.'
+    c.desc 'Prompt for additional notes. Input will be appended to any existing note.
+    If STDIN input (piped) is detected, it will be used as a note.'
     c.switch %i[n note], negatable: false
 
     c.desc 'Overwrite note instead of appending'
@@ -411,14 +415,14 @@ class App
 
       action = if args.count.positive?
                  args.join(' ').strip
-               elsif TTY::Which.exist?('gum') && options[:tagged].empty?
+               elsif $stdin.isatty && TTY::Which.exist?('gum') && options[:tagged].empty?
                  options = [
                    %(--placeholder "Enter a task to search for"),
                    '--char-limit=500',
                    "--width=#{TTY::Screen.columns}"
                  ]
                  `gum input #{options.join(' ')}`.strip
-               elsif options[:tagged].empty?
+               elsif $stdin.isatty && options[:tagged].empty?
                  puts NA::Color.template('{bm}Enter search string:{x}')
                  reader.read_line(NA::Color.template('{by}> {bw}')).strip
                end
@@ -467,7 +471,10 @@ class App
       add_tags = options[:tag].map { |t| t.sub(/^@/, '').wildcard_to_rx }
       remove_tags = options[:remove].map { |t| t.sub(/^@/, '').wildcard_to_rx }
 
-      line_note = if options[:note]
+      stdin_note = NA.stdin ? NA.stdin.split("\n") : []
+
+      line_note = if options[:note] && $stdin.isatty
+                    puts stdin_note unless stdin_note.nil?
                     if TTY::Which.exist?('gum')
                       args = ['--placeholder "Enter a note, CTRL-d to save"']
                       args << '--char-limit 0'
@@ -479,7 +486,8 @@ class App
                     end
                   end
 
-      note = line_note.nil? || line_note.empty? ? [] : line_note
+      note = stdin_note.empty? ? [] : stdin_note
+      note.concat(line_note) unless line_note.nil? || line_note.empty?
 
       target_proj = if options[:project]
                       options[:project]
@@ -497,10 +505,11 @@ class App
       elsif options[:todo]
         todo = []
         options[:todo].split(/ *, */).each do |a|
-          m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+          m = a.match(/^(?<req>[+\-!])?(?<tok>.*?)$/)
           todo.push({
                       token: m['tok'],
-                      required: !m['req'].nil?
+                      required: all_req || (!m['req'].nil? && m['req'] == '+'),
+                      negate: !m['req'].nil? && m['req'] =~ /[!\-]/
                     })
         end
         dirs = NA.match_working_dir(todo)
@@ -568,6 +577,9 @@ class App
     c.arg_name 'TODO_PATH'
     c.flag %i[in]
 
+    c.desc 'Include notes in output'
+    c.switch %i[notes], negatable: true, default_value: false
+
     c.desc 'Combine search tokens with OR, displaying actions matching ANY of the terms'
     c.switch %i[o or], negatable: false
 
@@ -619,10 +631,11 @@ class App
       if options[:in]
         todo = []
         options[:in].split(/ *, */).each do |a|
-          m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+          m = a.match(/^(?<req>[+\-!])?(?<tok>.*?)$/)
           todo.push({
                       token: m['tok'],
-                      required: !m['req'].nil?
+                      required: all_req || (!m['req'].nil? && m['req'] == '+'),
+                      negate: !m['req'].nil? && m['req'] =~ /[!\-]/
                     })
         end
       end
@@ -641,7 +654,7 @@ class App
                   [tokens]
                 end
 
-      NA.output_actions(actions, depth, files: files, regexes: regexes)
+      NA.output_actions(actions, depth, files: files, regexes: regexes, notes: options[:notes])
     end
   end
 
@@ -669,6 +682,9 @@ class App
     c.arg_name 'TODO_PATH'
     c.flag %i[in]
 
+    c.desc 'Include notes in output'
+    c.switch %i[notes], negatable: true, default_value: false
+
     c.desc 'Combine tags with OR, displaying actions matching ANY of the tags'
     c.switch %i[o or], negatable: false
 
@@ -721,10 +737,11 @@ class App
       if options[:in]
         todo = []
         options[:in].split(/ *, */).each do |a|
-          m = a.match(/^(?<req>\+)?(?<tok>.*?)$/)
+          m = a.match(/^(?<req>[+\-!])?(?<tok>.*?)$/)
           todo.push({
                       token: m['tok'],
-                      required: !m['req'].nil?
+                      required: all_req || (!m['req'].nil? && m['req'] == '+'),
+                      negate: !m['req'].nil? && m['req'] =~ /[!\-]/
                     })
         end
       end
@@ -737,7 +754,7 @@ class App
                                          project: options[:project],
                                          require_na: false)
       regexes = tags.delete_if { |token| token[:negate] }.map { |token| token[:token] }
-      NA.output_actions(actions, depth, files: files, regexes: regexes)
+      NA.output_actions(actions, depth, files: files, regexes: regexes, notes: options[:notes])
     end
   end
 
@@ -751,17 +768,17 @@ class App
       reader = TTY::Reader.new
       if args.count.positive?
         project = args.join(' ')
-      else
+      elsif
         project = File.expand_path('.').split('/').last
-        project = reader.read_line(NA::Color.template('{y}Project name {bw}> {x}'), value: project).strip
+        project = reader.read_line(NA::Color.template('{y}Project name {bw}> {x}'), value: project).strip if $stdin.isatty
       end
 
       target = "#{project}.#{NA.extension}"
 
       if File.exist?(target)
-        print NA::Color.template("{r}File {bw}#{target}{r} already exists, overwrite it? {br}y{w}/{bg}N{x} ")
-        res = reader.read_char
-        Process.exit 1 unless res =~ /y/i
+        res = NA.yn(NA::Color.template("{r}File {bw}#{target}{r} already exists, overwrite it"), default: false)
+        Process.exit 1 unless res
+
       end
 
       NA.create_todo(target, project)
@@ -942,8 +959,12 @@ class App
   long_desc 'Run without argument to list saved searches'
   arg_name 'SEARCH_TITLE', optional: true
   command %i[saved] do |c|
-    c.example 'na saved overdue', description: 'perform the search named "overdue"'
-    c.example 'na saved over', description: 'perform the search named "overdue", assuming no other searches match "over"'
+    c.example 'na tagged "+maybe,+priority<=3" --save maybelater', description: 'save a search called "maybelater"'
+    c.example 'na saved maybelater', description: 'perform the search named "maybelater"'
+    c.example 'na saved maybe',
+              description: 'perform the search named "maybelater", assuming no other searches match "may"'
+    c.example 'na maybe',
+              description: 'na run with no command and a single argument automatically performs a matching saved search'
     c.example 'na saved', description: 'list available searches'
 
     c.desc 'Open the saved search file in $EDITOR'
@@ -953,18 +974,14 @@ class App
     c.switch %i[d delete]
 
     c.action do |_global_options, options, args|
-      if options[:edit]
-        NA.edit_searches
-      end
+      NA.edit_searches if options[:edit]
 
       searches = NA.load_searches
       if args.empty?
         NA.notify("{bg}Saved searches stored in {bw}#{NA.database_path(file: 'saved_searches.yml')}")
         NA.notify(searches.map { |k, v| "{y}#{k}: {w}#{v}" }.join("\n"), exit_code: 0)
       else
-        if options[:delete]
-          NA.delete_search(args)
-        end
+        NA.delete_search(args) if options[:delete]
 
         keys = searches.keys.delete_if { |k| k !~ /#{args[0]}/ }
         NA.notify("{r}Search #{args[0]} not found", exit_code: 1) if keys.empty?
@@ -988,6 +1005,7 @@ class App
                   global[:cwd_as] =~ /^p/ ? :project : :tag
                 end
     NA.weed_cache_file
+    NA.notify("{dw}{ globals: #{NA.globals}, command_line: #{NA.command_line}, command: #{NA.command}}", debug: true)
     true
   end
 
@@ -998,10 +1016,21 @@ class App
   on_error do |exception|
     case exception
     when GLI::UnknownCommand
-      cmd = ['saved']
-      cmd.concat(ARGV.unshift(NA.command_line[0]))
+      if NA.command_line.count == 1
+        cmd = ['saved']
+        cmd.concat(ARGV.unshift(NA.command_line[0]))
+
+        exit run(cmd)
+      elsif NA.globals.include?('-a') || NA.globals.include?('--add')
+        cmd = ['add']
+        cmd.concat(NA.command_line)
+        NA.globals.delete('-a')
+        NA.globals.delete('--add')
+        cmd.unshift(*NA.globals)
 
-      exit run(cmd)
+        exit run(cmd)
+      end
+      true
     when SystemExit
       false
     else
@@ -1010,9 +1039,20 @@ class App
   end
 end
 
-NA.command_line = ARGV.dup
-NA.globals = NA.command_line.filter { |arg| arg =~ /^-/ }
-NA.command_line.delete_if { |arg| arg =~ /^-/ }
-@command = ARGV[0]
+NA.stdin = $stdin.read.strip if $stdin.stat.size.positive? || $stdin.fcntl(Fcntl::F_GETFL, 0).zero?
+NA.stdin = nil unless NA.stdin && NA.stdin.length.positive?
+
+NA.globals = []
+NA.command_line = []
+in_globals = true
+ARGV.each do |arg|
+  if arg =~ /^-/ && in_globals
+    NA.globals.push(arg)
+  else
+    NA.command_line.push(arg)
+    in_globals = false
+  end
+end
+NA.command = NA.command_line[0]
 
 exit App.run(ARGV)

data/lib/na/action.rb

@@ -2,9 +2,9 @@
 
 module NA
   class Action < Hash
-    attr_reader :file, :project, :parent, :tags, :line, :note
+    attr_reader :file, :project, :parent, :tags, :line
 
-    attr_accessor :action
+    attr_accessor :action, :note
 
     def initialize(file, project, parent, action, idx, note = [])
       super()
@@ -19,7 +19,12 @@ module NA
     end
 
     def to_s
-      "(#{@file}:#{@line}) #{@project}:#{@parent.join('>')} | #{@action}"
+      note = if @note.count.positive?
+               "\n#{@note.join("\n")}"
+             else
+               ''
+             end
+      "(#{@file}:#{@line}) #{@project}:#{@parent.join('>')} | #{@action}#{@note}"
     end
 
     def inspect
@@ -28,10 +33,11 @@ module NA
       @project: #{@project}
       @parent: #{@parent.join('>')}
       @action: #{@action}
+      @note: #{@note}
       EOINSPECT
     end
 
-    def pretty(extension: 'taskpaper', template: {}, regexes: [])
+    def pretty(extension: 'taskpaper', template: {}, regexes: [], notes: false)
       default_template = {
         file: '{xbk}',
         parent: '{c}',
@@ -41,7 +47,8 @@ module NA
         tags: '{m}',
         value_parens: '{m}',
         values: '{y}',
-        output: '%filename%parents| %action'
+        output: '%filename%parents| %action',
+        note: '{dw}'
       }
       template = default_template.merge(template)
 
@@ -58,6 +65,12 @@ module NA
       file_tpl = "#{template[:file]}#{file} {x}"
       filename = NA::Color.template(file_tpl)
 
+      note = if notes && @note.count.positive?
+               NA::Color.template("\n#{@note.map { |l| "  #{template[:note]}• #{l}{x}" }.join("\n")}")
+             else
+               ''
+             end
+
       action = NA::Color.template("#{template[:action]}#{@action.sub(/ @#{NA.na_tag}\b/, '')}{x}")
       action = action.highlight_tags(color: template[:tags],
                                      parens: template[:value_parens],
@@ -67,7 +80,8 @@ module NA
       NA::Color.template(template[:output].gsub(/%filename/, filename)
                           .gsub(/%project/, project)
                           .gsub(/%parents?/, parents)
-                          .gsub(/%action/, action.highlight_search(regexes))).gsub(/\\\{/, '{')
+                          .gsub(/%action/, action.highlight_search(regexes))
+                          .gsub(/%note/, note)).gsub(/\\\{/, '{')
     end
 
     def tags_match?(any: [], all: [], none: [])

data/lib/na/next_action.rb

@@ -3,7 +3,7 @@
 # Next Action methods
 module NA
   class << self
-    attr_accessor :verbose, :extension, :na_tag, :command_line, :globals, :global_file, :cwd_is, :cwd
+    attr_accessor :verbose, :extension, :na_tag, :command_line, :command, :globals, :global_file, :cwd_is, :cwd, :stdin
 
     ##
     ## Output to STDERR
@@ -14,7 +14,7 @@ module NA
     ## @param      debug      [Boolean] only display message if running :verbose
     ##
     def notify(msg, exit_code: false, debug: false)
-      return if debug && NA.verbose
+      return if debug && !NA.verbose
 
       $stderr.puts NA::Color.template("{x}#{msg}{x}")
       Process.exit exit_code if exit_code
@@ -116,31 +116,13 @@ module NA
     ## @param      files     [Array] The files
     ## @param      multiple  [Boolean] allow multiple selections
     ##
+    ## @return [String, Array] array if multiple
     def select_file(files, multiple: false)
-      if TTY::Which.exist?('fzf')
-        res = choose_from(files, prompt: 'Use which file?', multiple: multiple)
-        unless res
-          notify('{r}No file selected, cancelled', exit_code: 1)
-        end
+      res = choose_from(files, prompt: multiple ? 'Select files' : 'Select a file', multiple: multiple)
 
-        multiple ? res.split("\n") : res.strip
-      elsif TTY::Which.exist?('gum')
-        args = [
-          '--cursor.foreground="151"',
-          '--item.foreground=""'
-        ]
-        args.push('--no-limit') if multiple
-        res = `echo #{Shellwords.escape(files.join("\n"))}|#{TTY::Which.which('gum')} choose #{args.join(' ')}`
-        multiple ? res.split("\n") : res.strip
-      else
-        reader = TTY::Reader.new
-        puts
-        files.each.with_index do |f, i|
-          puts NA::Color.template(format("{bw}%<idx> 2d{xw}) {y}%<file>s{x}\n", idx: i + 1, file: f))
-        end
-        res = reader.read_line(NA::Color.template('{bw}Use which file? {x}')).strip.to_i
-        files[res - 1]
-      end
+      notify('{r}No file selected, cancelled', exit_code: 1) unless res && res.length.positive?
+
+      res
     end
 
     def shift_index_after(projects, idx, length = 1)
@@ -166,33 +148,12 @@ module NA
       return [projects, actions] if actions.count == 1 || all
 
       options = actions.map { |action| "#{action.line} % #{action.parent.join('/')} : #{action.action}" }
-      res = if TTY::Which.exist?('fzf')
-              choose_from(options, prompt: 'Make a selection: ', multiple: true, sorted: true)
-            elsif TTY::Which.exist?('gum')
-              args = [
-                '--cursor.foreground="151"',
-                '--item.foreground=""',
-                '--no-limit'
-              ]
-              `echo #{Shellwords.escape(options.join("\n"))}|#{TTY::Which.which('gum')} choose #{args.join(' ')}`.strip
-            else
-              reader = TTY::Reader.new
-              puts
-              options.each.with_index do |f, i|
-                puts NA::Color.template(format("{bw}%<idx> 2d{xw}) {y}%<action>s{x}\n", idx: i + 1, action: f))
-              end
-              result = reader.read_line(NA::Color.template('{bw}Use which file? {x}')).strip
-              if result && result.to_i.positive?
-                options[result.to_i - 1]
-              else
-                nil
-              end
-            end
+      res = choose_from(options, prompt: 'Make a selection: ', multiple: true, sorted: true)
 
       NA.notify('{r}Cancelled', exit_code: 1) unless res && res.length.positive?
 
       selected = []
-      res.split(/\n/).each do |result|
+      res.each do |result|
         idx = result.match(/^(\d+)(?= % )/)[1]
         action = actions.select { |a| a.line == idx.to_i }.first
         selected.push(action)
@@ -327,6 +288,7 @@ module NA
                         projects.select { |proj| proj.project =~ /^#{action.parent.join(':')}$/ }.first
                       end
 
+
         indent = "\t" * target_proj.indent
         note = note.split("\n") unless note.is_a?(Array)
         note = if note.empty?
@@ -439,7 +401,7 @@ module NA
     ## @param      files    [Array] The files actions originally came from
     ## @param      regexes  [Array] The regexes used to gather actions
     ##
-    def output_actions(actions, depth, files: nil, regexes: [])
+    def output_actions(actions, depth, files: nil, regexes: [], notes: false)
       return if files.nil?
 
       template = if files.count.positive?
@@ -457,10 +419,11 @@ module NA
                  else
                    '%parent%action'
                  end
+      template += '%note' if notes
 
       files.map { |f| notify("{dw}#{f}", debug: true) } if files
 
-      puts(actions.map { |action| action.pretty(template: { output: template }, regexes: regexes) })
+      puts(actions.map { |action| action.pretty(template: { output: template }, regexes: regexes, notes: notes) })
     end
 
     ##
@@ -536,7 +499,7 @@ module NA
         parent = []
         in_action = false
         content.split("\n").each.with_index do |line, idx|
-          if line =~ /^([ \t]*)([^\-@()]+?): *(@\S+ *)*$/
+          if line =~ /^([ \t]*)([^\-][^@()]+?): *(@\S+ *)*$/
             in_action = false
             proj = Regexp.last_match(2)
             indent = line.indent_level
@@ -783,6 +746,12 @@ module NA
       required = search.filter { |s| s[:required] }.map { |t| t[:token] }
       negated = search.filter { |s| s[:negate] }.map { |t| t[:token] }
 
+      optional.push('*') if required.count.zero? && negated.count.positive?
+      if required == negated
+        required = ['*']
+        optional = ['*']
+      end
+
       NA.notify("{dw}Optional directory regex: {x}#{optional.map(&:dir_to_rx)}", debug: true)
       NA.notify("{dw}Required directory regex: {x}#{required.map(&:dir_to_rx)}", debug: true)
       NA.notify("{dw}Negated directory regex: {x}#{negated.map { |t| t.dir_to_rx(distance: 1, require_last: false) }}", debug: true)
@@ -815,21 +784,41 @@ module NA
     ## @param      sorted    [Boolean] If true, sort selections alphanumerically
     ## @param      fzf_args  [Array] Additional fzf arguments
     ##
+    ## @return [String, Array] array if multiple is true
     def choose_from(options, prompt: 'Make a selection: ', multiple: false, sorted: true, fzf_args: [])
       return nil unless $stdout.isatty
 
-      default_args = [%(--prompt="#{prompt}"), "--height=#{options.count + 2}", '--info=inline']
-      default_args << '--multi' if multiple
-      default_args << '--bind ctrl-a:select-all'
-      header = "esc: cancel,#{multiple ? ' tab: multi-select, ctrl-a: select all,' : ''} return: confirm"
-      default_args << %(--header="#{header}")
-      default_args.concat(fzf_args)
       options.sort! if sorted
 
-      res = `echo #{Shellwords.escape(options.join("\n"))}|#{TTY::Which.which('fzf')} #{default_args.join(' ')}`
+      res = if TTY::Which.exist?('fzf')
+              default_args = [%(--prompt="#{prompt}"), "--height=#{options.count + 2}", '--info=inline']
+              default_args << '--multi' if multiple
+              default_args << '--bind ctrl-a:select-all' if multiple
+              header = "esc: cancel,#{multiple ? ' tab: multi-select, ctrl-a: select all,' : ''} return: confirm"
+              default_args << %(--header="#{header}")
+              default_args.concat(fzf_args)
+              `echo #{Shellwords.escape(options.join("\n"))}|#{TTY::Which.which('fzf')} #{default_args.join(' ')}`.strip
+            elsif TTY::Which.exist?('gum')
+              args = [
+                '--cursor.foreground="151"',
+                '--item.foreground=""'
+              ]
+              args.push '--no-limit' if multiple
+              puts NS::Color.template("{bw}#{prompt}{x}")
+              `echo #{Shellwords.escape(options.join("\n"))}|#{TTY::Which.which('gum')} choose #{args.join(' ')}`.strip
+            else
+              reader = TTY::Reader.new
+              puts
+              options.each.with_index do |f, i|
+                puts NA::Color.template(format("{bw}%<idx> 2d{xw}) {y}%<action>s{x}\n", idx: i + 1, action: f))
+              end
+              result = reader.read_line(NA::Color.template("{bw}#{prompt}{x}")).strip
+              result.to_i&.positive? ? options[result.to_i - 1] : nil
+            end
+
       return false if res.strip.size.zero?
 
-      res
+      multiple ? res.split(/\n/) : res
     end
 
     def parse_search(tag, negate)

data/lib/na/prompt.rb

@@ -7,22 +7,59 @@ module NA
       def prompt_hook(shell)
         case shell
         when :zsh
+          cmd = if NA.global_file
+                  case NA.cwd_is
+                  when :project
+                    'na next --proj $(basename "$PWD")'
+                  when :tag
+                    'na tagged $(basename "$PWD")'
+                  else
+                    NA.notify('When using a global file, a prompt hook requires `--cwd_as [tag|project]`', exit_code: 1)
+                  end
+                else
+                  'na next'
+                end
           <<~EOHOOK
             # zsh prompt hook for na
-            chpwd() { na next }
+            chpwd() { #{cmd} }
           EOHOOK
         when :fish
+          cmd = if NA.global_file
+                  case NA.cwd_is
+                  when :project
+                    'na next --proj (basename "$PWD")'
+                  when :tag
+                    'na tagged (basename "$PWD")'
+                  else
+                    NA.notify('When using a global file, a prompt hook requires `--cwd_as [tag|project]`', exit_code: 1)
+                  end
+                else
+                  'na next'
+                end
           <<~EOHOOK
             # Fish Prompt Command
             function __should_na --on-variable PWD
-              test -s (basename $PWD)".#{NA.extension}" && na next
+              test -s (basename $PWD)".#{NA.extension}" && #{cmd}
             end
           EOHOOK
         when :bash
+          cmd = if NA.global_file
+                  case NA.cwd_is
+                  when :project
+                    'na next --proj $(basename "$PWD")'
+                  when :tag
+                    'na tagged $(basename "$PWD")'
+                  else
+                    NA.notify('When using a global file, a prompt hook requires `--cwd_as [tag|project]`', exit_code: 1)
+                  end
+                else
+                  'na next'
+                end
+
           <<~EOHOOK
             # Bash PROMPT_COMMAND for na
             last_command_was_cd() {
-              [[ $(history 1|sed -e "s/^[ ]*[0-9]*[ ]*//") =~ ^((cd|z|j|jump|g|f|pushd|popd|exit)([ ]|$)) ]] && na next
+              [[ $(history 1|sed -e "s/^[ ]*[0-9]*[ ]*//") =~ ^((cd|z|j|jump|g|f|pushd|popd|exit)([ ]|$)) ]] && #{cmd}
             }
             if [[ -z "$PROMPT_COMMAND" ]]; then
               PROMPT_COMMAND="eval 'last_command_was_cd'"
@@ -46,7 +83,7 @@ module NA
       def show_prompt_hook(shell)
         file = prompt_file(shell)
 
-        $stderr.puts NA::Color.template("{bw}# Add this to {y}#{file}{x}")
+        NA.notify("{bw}# Add this to {y}#{file}{x}")
         puts prompt_hook(shell)
       end
 
@@ -54,8 +91,8 @@ module NA
         file = prompt_file(shell)
 
         File.open(File.expand_path(file), 'a') { |f| f.puts prompt_hook(shell) }
-        $stderr.puts NA::Color.template("{y}Added {bw}#{shell}{xy} prompt hook to {bw}#{file}{xy}.{x}")
-        $stderr.puts NA::Color.template("{y}You may need to close the current terminal and open a new one to enable the script.{x}")
+        NA.notify("{y}Added {bw}#{shell}{xy} prompt hook to {bw}#{file}{xy}.{x}")
+        NA.notify("{y}You may need to close the current terminal and open a new one to enable the script.{x}")
       end
     end
   end

data/lib/na/version.rb

@@ -1,3 +1,3 @@
 module Na
-  VERSION = '1.2.5'
+  VERSION = '1.2.7'
 end

data/src/README.md

@@ -9,11 +9,11 @@
 _If you're one of the rare people like me who find this useful, feel free to
 [buy me some coffee][donate]._
 
-The current version of `na` is <!--VER-->1.2.4<!--END VER-->.
+The current version of `na` is <!--VER-->1.2.6<!--END VER-->.
 
 `na` ("next action") is a command line tool designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-formatted files (but any plain text format will do), looking for `@na` tags (or whatever you specify) in todo files in your current folder. 
 
-Used with Taskpaper files, it can add new todo items quickly from the command line, automatically tagging them as next actions.
+Used with Taskpaper files, it can add new action items quickly from the command line, automatically tagging them as next actions. It can also mark actions as completed, delete them, archive them, and move them between projects.
 
 It can also auto-display next actions when you enter a project directory, automatically locating any todo files and listing their next actions when you `cd` to the project (optionally recursive). See the [Prompt Hooks](#prompt-hooks) section for details.
 
@@ -30,9 +30,13 @@ If you don't have Ruby/RubyGems, you can install them pretty easily with Homebre
 
 <!--JEKYLL> You can find the na source code (MIT license) on [GitHub][].-->
 
+### Optional Dependencies
+
+If you have [gum][] installed, na will use it for command line input when adding tasks and notes. If you have [fzf][] installed, it will be used for menus, falling back to gum if available.
+
 ### Features
 
-You can list next actions in files in the current directory by typing `na`. By default, `na` looks for `*.taskpaper` files and extracts items tagged `@na` and not `@done`. All of these can be changed in the configuration.
+You can list next actions in files in the current directory by typing `na`. By default, `na` looks for `*.taskpaper` files and extracts items tagged `@na` and not `@done`. This can be modified to work with a single global file, and all of these options can be changed in the configuration.
 
 #### Easy matching
 
@@ -52,6 +56,16 @@ If found, it will try to locate an `Inbox:` project, or create one if it doesn't
 
 You can mark todos as complete, delete them, add and remove tags, change priority, and even move them between projects with the `na update` command.
 
+### Terminology
+
+**Todo**: Refers to a todo file, usually a TaskPaper document
+
+**Project**: Refers to a project within the TaskPaper document, specified by an alphanumeric name (spaces allowed) followed by a colon. Projects can be nested by indenting a tab beyond the parent projects indentation.
+
+**Action**: Refers to an individual task, specified by a line starting with a hyphen (`-`)
+
+**Note**: Refers to lines appearing between action lines that start without hyphens. The note is attached to the preceding action regardless of indentation.
+
 ### Usage
 
 ```
@@ -66,6 +80,12 @@ Example: `na add This feature @idea I have`
 
 If you run the `add` command with no arguments, you'll be asked for input on the command line.
 
+###### Adding notes
+
+Use the `--note` switch to add a note. If STDIN (piped) input is present when this switch is used, it will be included in the note. A prompt will be displayed for adding additional notes, which will be appended to any STDIN note passed. Press CTRL-d to end editing and save the note. 
+
+Notes are not displayed by the `next/tagged/find` commands unless `--notes` is specified.
+
 ```
 @cli(bundle exec bin/na help add)
 ```
@@ -100,6 +120,8 @@ Examples:
 - `na next -d 3` (list all next actions in the current directory and look for additional files 3 levels deep from there)
 - `na next marked2` (show next actions from another directory you've previously used na on)
 
+To see all next actions across all known todos, use `na next "*"`. You can combine multiple arguments to see actions across multiple todos, e.g. `na next marked nvultra`.
+
 ```
 @cli(bundle exec bin/na help next)
 ```
@@ -120,6 +142,9 @@ Search names can be partially matched when calling them, so if you have a search
 
 Run `na saved` without an argument to list your saved searches.
 
+> As a shortcut, if `na` is run with one argument that matches the name of a saved search, it will execute that search, so running `na maybe` is the same as running `na saved maybe`.
+<!--JEKYLL{:.tip}-->
+
 ```
 @cli(bundle exec bin/na help saved)
 ```
@@ -158,11 +183,27 @@ You can specify a particular todo file using `--file PATH` or any todo from hist
 
 If more than one file is matched, a menu will be presented, multiple selections allowed. If multiple actions match the search within the selected file(s), a menu will be presented. If you have fzf installed, you can select one action to update with return, or use tab to mark multiple tasks to which the action will be applied. With gum you can use j, k, and x to mark multiple actions. Use the `--all` switch to force operation on all matched tasks, skipping the menu.
 
-Any time an update action is carried out, a backup of the file before modification will be made in the same directory with a `.` prepended and `.bak` appended (e.g. `marked.taskpaper` is copied to `.marked.taskpaper.bak`). Only one undo step is available, but if something goes wrong (and this feature is still experimental, so be wary), you can just copy the "~" file back to the original.
+Any time an update action is carried out, a backup of the file before modification will be made in the same directory with a `.` prepended and `.bak` appended (e.g. `marked.taskpaper` is copied to `.marked.taskpaper.bak`). Only one undo step is available, but if something goes wrong (and this feature is still experimental, so be wary), you can just copy the ".bak" file back to the original.
+
+###### Marking a task as complete
+
+You can mark an action complete using `--finish`, which will add a dated @done tag to the action. You can also mark it @done and immediately move it to the Archive project using `--archive`.
+
+If you just want the action to stop appearing as a "next action," you can remove the next action tag using `--remove na` (or whatever your next action tag is configured as).
+
+If you want to permanently delete an action, use `--delete` to remove it entirely.
+
+###### Moving between projects
 
 You can specify a new project for an action (moving it) with `--proj PROJECT_PATH`. A project path is hierarchical, with each level separated by a colon or slash. If the project path provided roughly matches an existing project, e.g. "mark:bug" would match "Marked:Bugs", then that project will be used. If no match is found, na will offer to generate a new project/hierarchy for the path provided. Strings will be exact but the first letter will be uppercased.
 
-See the help output for a list of available actions.
+###### Adding notes
+
+Use the `--note` switch to add a note. If STDIN (piped) input is present when this switch is used, it will be included in the note. A prompt will be displayed for adding additional notes, which will be appended to any STDIN note passed. Press CTRL-d to end editing and save the note.
+
+Notes are not displayed by the `next/tagged/find` commands unless `--notes` is specified.
+
+See the help output for a list of all available actions.
 
 ```
 @cli(bundle exec bin/na help update)
@@ -172,6 +213,9 @@ See the help output for a list of available actions.
 
 Global options such as todo extension and default next action tag can be stored permanently by using the `na initconfig` command. Run na with the global options you'd like to set, and add `initconfig` at the end of the command. A file will be written to `~/.na.rc`. You can edit this manually, or just update it using the `initconfig --force` command to overwrite it with new settings.
 
+> You can see all available global options by running `na help`.
+<!--JEKYLL{:.tip}-->
+
 Example: `na --ext md --na_tag next initconfig --force`
 
 When this command is run, it doesn't include options for subcommands, but inserts placeholders for them. If you want to permanently set an option for a subcommand, you'll need to edit `~/.na.rc`. For example, if you wanted the `next` command to always recurse 2 levels deep, you could edit it to look like this:
@@ -202,12 +246,14 @@ When using a global file, you can additionally include `--cwd_as TYPE` to determ
 
 #### Add tasks at the end of a project
 
-By default, tasks are added at the top of the target project (Inbox, etc.). If you prefer new tasks to go at the bottom by default, include `--add_at end` as a global option when running `initconfig`.
+By default, tasks are added at the top of the target project (Inbox, etc.). If you prefer new tasks to go at the end of the project by default, include `--add_at end` as a global option when running `initconfig`.
 
 ### Prompt Hooks
 
 You can add a prompt command to your shell to have na automatically list your next actions when you `cd` into a directory. To install a prompt command for your current shell, just run `na prompt install`. It works with Zsh, Bash, and Fish. If you'd rather make the changes to your startup file yourself, run `na prompt show` to get the hook and instructions printed out for copying.
 
+If you're using a single global file, you'll need `--cwd_as` to be `tag` or `project` for a prompt command to work. na will detect which system you're using and provide a prompt command that lists actions based on the current directory using either project or tag.
+
 > You can also get output for shells other than the one you're currently using by adding "bash", "zsh", or "fish" to the show or install command.
 <!--JEKYLL{:.tip}-->
 
@@ -216,9 +262,6 @@ You can add a prompt command to your shell to have na automatically list your ne
 
 After installing a hook, you'll need to close your terminal and start a new session to initialize the new commands.
 
-### Misc
-
-If you have [gum][] installed, na will use it for command line input when adding tasks and notes. If you have [fzf][] installed, it will be used for menus, falling back to gum if available.
 
 [fzf]: https://github.com/junegunn/fzf
 [gum]: https://github.com/charmbracelet/gum

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: na
 version: !ruby/object:Gem::Version
-  version: 1.2.5
+  version: 1.2.7
 platform: ruby
 authors:
 - Brett Terpstra
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-26 00:00:00.000000000 Z
+date: 2022-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake