CARNET(1)

NAME
carnet - note taking logbook helper

SYNOPSIS
carnet [-d|--debug] [-a|--activity] [-r|--readonly]
carnet [-d|--debug] [-h] [--help] [-v] [--version]
carnet [-d|--debug] [-ef|--edit-feuillet [<YYYY-MM-DDThh:mm>]]
carnet [-d|--debug] [-f|--feuillet [<YYYY-MM-DDThh:mm>]]
carnet [-d|--debug] [-lm|--list-modules]
carnet [-d|--debug] [-m|--module <module> [<arguments> ...]]
carnet [-d|--debug] [-s|--search [<pattern> ...]]
carnet [-d|--debug] [-t|--todo [<state>]]
carnet [-d|--debug] [--done [<state>]]

DESCRIPTION
carnet is a logbook and note taking helper. It provides a way to record seamlessly journal entries, along automated recording of the time and date and all sorts of interesting information, like recorded calendar(1) activities, or what could be playing on music players. Invoked without arguments, carnet opens straight the log book to create a new entry at the current time and date at the tail of the file. Use cases include, but are not limited to: scratch pad for taking notes, timesheet recording, or notes storage and retrieval facility; the killer feature is that it may be all at once as the needs of the writer evolve over time.

The "carnet" log book is a set of text files, one per week, made of entries named "feuillets" separated by a time stamp, and specific markers to separate days of the week; this avoids exploding the file size of a long running log file typed for a while by a proficient writer, while also avoiding the explosion of file numbers that could appear with compulsive writers.

OPTIONS

-a, --activity
    print out a histogram of activity for each week.

-d, --debug
    print out debug information upon invocation.

-ef, --edit-feuillet [<YYYY-MM-DDThh:mm>]
    edit the entry pointed to by the time stamp in somewhat normalized format; if no time stamp is passed, it edits the register.txt file of the carnet.

-f, --feuillet [<YYYY-MM-DDThh:mm>]
    print out the entry pointed to by the time stamp in somewhat normalized format; the format is also highlighted to facilitate navigation between entries of carnet; if no time stamp is passed, it opens the register.txt file of the carnet.

-h  print out the short usage notice.

--help
    print out the full description, usage and help message.

-l, --list-modules
    list module programs shipped within a given carnet; see --module for modules purpose.

-m, --module <module> [<argument> ...]
    execute a module program shipped within a given carnet; this is intended for power users as an escape hatch to e.g. implement customized search engines, or specific activity metrics.

-r, --readonly
    look up the carnet in read-only mode, without appending a new entry.

-s, --search [<pattern> ...]
    look up log book entries matching the provided search patterns; as a convenience, time stamps are highlighted for consumption by the option to retrieve feuillets; the command dumps the entire carnet in output if no pattern is given; multiple patterns will be treated as or'ed.

-t, --todo [<state>]
    list "todo" items found in the carnet; todo items can be materialized using a sort of square materialized by brackets like '[ ]' at the beginning of a line; the blank space may be later erased to materialize the new state of the task, e.g. '[*]' or '[DONE]' at the discretion of the writer. The optional state argument may be used to list tasks materialized with a given state, again mostly free form at the discretion of the writer.

-v  print out the program version.

--version
    print out the program version and license terms.

--done [<state>]
    shortcut for common markers representing "todo" items in the state done, primarily provided as a convenience to match "[*]" and other common patterns marking tasks completed.

--motd
    print out the message of the day.

--edit-motd
    edit the motd.txt file containing the message of the day.

ENVIRONMENT

CARNET_DIR
    indicates the directory in which the carnet content is stored. The default is to put it in the carnet/ directory within the user's default "Documents" directory.

CARNET_EDITOR
    overrides EDITOR and VISUAL environment variables settings. The default is unset.

CARNET_LANG
    overrides LANG environment variable. This is unset by default.

CARNET_LESS
    overrides LESS environment variable. This is unset by default.

CARNET_OVERTIME
    indicate after how many hours work on the carnet is considered overtime for the day; single integer values will express hours, otherwise durations may be expressed with the hh:mm format; unset or zero value will disable the option.

CARNET_PAGER
    provide a custom pager. This is unset by default. Contrary to previous carnet versions, this does not override PAGER, which is now unused.

FILES

YYYY-WW.txt
    these files, formated after the week-year and the week number, will store the plain text content of carnet entries; pretty often, those are the only files that are going to be present in a carnet directory, and that's fine.

register.txt
    this file can serve as landing pad for navigating through a complex carnet: it can store references to interesting feuillets, common search patterns or all kind of free form information that should be easy to retrieve; it does not have to be present if people don't feel the need to have one.

motd.txt
    a few lines can be dropped in this file, they will be printed out after the addition of an entry; this can be used to give and preserve the general orientation of the theme of the carnet; it is better to keep it simple and short, for example the vulcan idiom "live long and prosper"; having none is also perfectly fine.

EXAMPLES

  Main usage:

carnet
    without further ado, start editing immediately a new feuillet at the current time stamp; this is the main use of carnet: to record a note and give it a time stamp without having to think about it.

carnet -s test
    search and retrieve feuillets containing the character string "test"; pattern matching is case insensitive and the feuillet will highlight the matching strings.

carnet -s it.s.a.sample.sentence
    search and retrieve feuillets containing the sentence "It's a sample sentence". Note that the '.' character is a regex that will be passed to awk, therefore will match any character, including space ' ', straight quote '\'', or carriage return '\n'; this is notably useful for finding long sentences for which one may not recall where it might have its line broken.

carnet -r
    read through carnet entries of the current week; this is useful to wrap up weekly activity reports.

  Task management:

carnet -t
    search and retrieve items left to do; they are identified by a "[ ]" or a "TODO:" at the beginning of a line of the feuillet.

carnet --done
    search and retrieve items done.

carnet -t pending
    search and retrieve items to do but in pending state due to not having been actionable at some point.

  Zettelkasten navigation:

carnet -f 2025-07-05T18:23
    retrieve the feuillet recorded on July 5th 2025 at 18:23; feuillet retrieval will highlight RFC 3339 compliant time stamps to facilitate navigation through feuillets that reference each others.

carnet -ef 2025-07-05T18:23
    open the text editor at the corresponding feuillet to bring modifications to it; this is useful for instance to cross reference with a feuillet in the future and weave further connections as the carnet grows.

carnet -f
    display the register of the carnet; this is useful to document aspects of a specific carnet to help with navigation throughout it, like time stamps of useful feuillets, or documentation of task management statuses.

carnet -ef
    open the register of the carnet for edition.

  Escape hatches:

carnet -m hello world
    invoke an executable file called "hello" and localised in the carnet directory, with argument "world"; this is useful to implement context specific user custom commands.

carnet -lm
    list modules available in the carnet directory that can be invoked with --module; this is useful when dealing with a hoard of custom scripts.

REPORTING BUGS
People are kindly invited to report issues discovered in carnet by email to Étienne Mollier <emollier@emlwks999.eu>. Here after are some known issues that are left to be resolved for the present version.

carnet relies essentially on plain text editors, making it poorly suited for drawing lovely pictures on the fly. Users are advised to make use of ascii art instead, or use a graphical alternative like rednotebook, available at <https://rednotebook.app/>.

It is currently poorly localised. Hopefully it will be resolved in a near future.

While the --search capability degraded somewhat gracefully with mawk implementation, its current behavior currently heavily relies on gawk.

<https://emlwks999.eu/~emollier/src/carnet/> may provide newer versions that resolve some problems, check also your distributor's updates if need be.

COPYRIGHT
Copyright © 2024-2026, Étienne Mollier <emollier@emlwks999.eu>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.