-
-
Notifications
You must be signed in to change notification settings - Fork 66
Configuration Reference
All default config options should be found in the file config.cc of astroid.
This page is a work in progress to document all config options available in Astroid. Feel free to contribute.
This page describes every configation option for astroid.
Each option is an entry in the astroid config file
(typically $HOME/.config/astroid/config see also
Astroid-setup)
We describe the options in a dotted notation like for example
astroid.config.version. In the actual file this means the option can
be found as follows.
{
"astroid" : {
"config" : {
"version" : "9"
}
}
}
That is, follow the "path" to the "version" option by going via "astroid" and "config".
The examples given is what you would write on the line where you find the option, so for the above an example would look like:
"version" : "9"
This notation saves us from continuously writing out the whole JSON tree and makes the document more readable.
Options are always written between double quotes, but do have certain types. Possible types:
-
string: "A line of text" -
file-path: a path to a file in the filesystem -
directory-path: a path to a directory in the filesystem -
rgb hex: a css-like color specification in #rrggbb format -
boolean: "true" or "false" -
integer: a number -
float: floating point number (ex.0.5) -
list: a, comma, separated, list
[comment]: # detail value restrictions of the types
log.levellog.sysloglog.stdout
Type : integer
Default : none, generated by astroid on startup
The version number of the config in use. This setting is used by astroid internally to help you with upgrading to newer astroid version which introduce new configuration items. This setting is normally not changed by the user.
Type : boolean
Default : false
This option can be helpful while you are configuring your astroid setup, which may be a bit of work. When set to true, this option does a dry-run on sending messages, that is the program does not actually send the messages, but otherwise behaves as if it was normally configured.
Type : filepath
Default : Depends on the [notmuch] configuration file location
This should point to your notmuch configuration file path. Astroid reads some settings from your notmuch configuration and uses them. If the path starts with a tilde it will be expanded to the current user's home directory. This setting is typically automatically configured when you first start using astroid (see: Astroid-setup).
If the NOTMUCH_CONFIG environment variable is set, it will be honored over this configuration option.
"notmuch_config": "\/home\/alice\/.notmuch-config"
For file paths in the config, we need to escape the / character by
preceding it with a backslash.
Type : Integer
Default : 0
Astroid's interface will display hints on several occasions to guide the user through certain actions (e.g. how to edit a draft email or how to cancel an email being sent). These hints are assigned a level.
This option enables you to filter out some hints by level. The higher you set this option, the less hints will be displayed.
By default, it is 0, i.e. only hints for which Astroid has assigned
a level above 0 will be displayed.
To ensure that all hints are displayed, set this to -1.
"level": "-1"
[comment]: # TODO: make inventory of hints and table them up here, grouped by level
Type: string
Default: default
Set font of embedded terminal. Values are parsed using Pango and should conform to that format.
default or empty uses default monospace font (same as thread-index).
Type: integer
Default: 10
Sets the height of the embedded terminal.
When astroid opens, you typically see a list of threads first; the thread-index. The options in this section are applicable to these thread-index screen.
Type : integer
Default : 6
When scrolling though an index, for example with the default key "J" this is the amount of rows astroid scrolls. So, larger values make you jump faster through the index and smaller values make you jump slower.
A value smaller than 2 really makes no sense, but 1 will still work. Anything smaller or even negative will disable the jump.
Type : string
Default : "newest"
This option determines how the threads in the index are sorted for display. The possible values for this option are:
- "newest" (default) : newest threads first (based on last msg?)
- "oldest" : oldest threads first (based on last msg?)
- "messageid" : sort by descending(?) messageid
- "unsorted" : no attempt is made by astroid to sort the threads
Type : integer
Default : 250
This option is unused at the moment.
Type : string
Default : "default"
Either the text "default" or a so called Pango FontDescription
describing what font to use in the index.
A bit more information on a Pango FontDescription can be found at: http://www.pygtk.org/pygtk2reference/class-pangofontdescription.html#constructor-pangofontdescription
Type : integer
Default : 2
The amount of vertical space, in pixels(?) to leave as spacing between each thread in the index.
Type : integer
Default : 10
The amount of characters to reserve for the date column
Type : integer
Default : 4
The amount of characters to reserve for the message count column
Type : integer
Default : 20
The amount of characters to reserve for the authors column
Type : rgb hex
Default : #807d74
A specification of the foreground color of subjects in the thread-index screen.
Type : rgb hex
Default : #000000
Specification of the foreground color of the subjects when the thread line has the focus in the thread-index screen.
Type : rgb hex
Default : ""
Specification of the background color in the thread-index screen. Empty mean that the GTK theme configurationb decides what to do with a selection.
Type : integer
Default : 80
The amount of characters to reserver for displaying the tags.
Type : rgb hex
Default : #e5e5e5
Tags get assigned a color out of a range automatically based on their name. This option value determines the upper value of the colors in the range.
Type : rgb hex
Default : #333333
Tags get assigned a color out of a range automatically based on their name. This option value determines the lower value of the colors in the range.
Type : float
Default : 0.5
This fraction determines how transparent tags are displayed and ranges from 0 to 1. A value of 0 would mean that the tags are totally transparent and a value of 1 means totally oblique.
The option is called alpha because a common technique to get things
to display with the illusion of transparency is
called
Alpha compositing
If it were me, i'd have called it transparency
Type : list
Default : attachment,flagged,unread
A list of tags which you do not want to see in the tag display. Typically these are tags for which another visual clue exists already. For example, the attachment icon shows that there is an attachment, so the tag is redundant and is hidden by default.
When drilling down on a thread a screen opens where you can view a summary of the individual messages in a thread; the thread view. The options in this section apply to all of these thread-view screens.
Type : boolean
Default : false
If a message has multiple parts and one of them is html, you can choose to have that part opened by an external application (typically your internet browser) or have astroid render it inside the thread-view.
Type : string
Default : "xdg-open"
If a message contains links to external content, use the value of this option to spawn an external program to open such links. The link is taken from the message and appended to the configured string at the end.
Type : directory-path
Default : "~"
This option configures the default directory where to save messages.
Type : boolean
Default : false
If this option is set to true the messages in the thread-view are
indented with respect to their parent if a message is a reply to it
thus forming a 'tree' of the messages. This might make it easier to
navigate long threads.
Type : boolean
Default : true
Astroid has the option to prettify certain pieces of code in messages. This options is the main switch to enable this feature. See the options below on how to fine-tune it.
For the code prettifying astroid makes out calls to an external site which runs https://github.com/google/code-prettify
Type : list
Default : ""
Only prettify messages which are tagged with a tag contained in this
option. If the option is left empty, prettifying is done for all
messages, assuming the code_prettify_enable option has been set to
true
Type : string
Default : "```"
The contents of this option is used as the trigger for astroid where to start prettifying things.
Type : boolean
Default : true
Regardless of the prettify_for_tags setting you can enable
prettifying code when a mail is a patch. The definition that astroid
uses to determine if a message is a patch has 2 criteria:
- the subject matches the regular expression
\\[PATCH.*\\] - the subject does NOT start with
RE:, likely making the message a reply.
If those 2 conditions are met astroid considers the message a patch
and if this option is set to true will enable prettifying for that
message.
Type : boolean
Default : true
Gravatar is a system which maps email addresses to images, or avatars, with the
intent to show next to the email-adres. This mapping is provided by
the site https://gravatar.com.
If you set this option to true, astroid will send an email-address to
gravator.com and retrieve an avatar-image stored there for the owner
of that email-address.
Type : float
Default : .5
When viewing a message, the tag unread will be removed, because the
message has been viewed. This option configures the amount of time
astroid will wait before doing that.
The idea is that you can see that the message was unread while
viewing the message.
Type : boolean
Default : true
In the thread view messages have two states, they are either collapsed
(showing just a summary) or expanded (showing the whole message). This
toggle makes messages that are flagged (i.e. have that tag) be
expanded by default.
- thread_view.preferred_type: either plain (default) or html.
- thread_view.preferred_html_only: bool, (default: false), show html part if there are no other preferred parts. (requries thread_view.open_html_part_external == false).
- thread_view.allow_remote_when_encrypted, bool (default: false) allow remote images when any one message is encrypted (#499)
General options, surprisingly all about how time and dates should be displayed on the screen.
Type : string
Default : "local"
This option specifies how time should be displayed and can have 4 values:
- "local" (default) : the locale on the machine determines how to show time
- "12h" : use a 12-hour notation
- "24h" : use a 24-hour notation
- "year": use the format described in general.time.same_year and general.time.diff_year.
Type : string
Default : "%b %-e"
If messages are from the same year as the current date, this format is used to display the date of the message.
Type : string
Default : "%x"
If messages are from different year than the current date, this format is used to display the date of the message.
Type: bool Default: true
Log to stdout.
Type: bool Default: false
Log to syslog.
Type: string
Default: debug (Debug build), info (Release build)
Possible values: trace, debug, info, warning, error, fatal
Options related to editing and composing messages.
Type : string
Default : "gvim -geom 10x10 --servername %2 --socketid %3 -f -c 'set ft=mail' '+set fileencoding=utf-8' '+set ff=unix' '+set enc=utf-8' '+set fo+=w' %1"
This option allows you to specify the exact command line to use for editing messages. See Customizing-editor for all the details.
Type : boolean
Default : true
Set this flag to true when the editor is external, the instructs
astroid that editing should not be embedded in its own windows and
just the file argument is passed through to the editor.cmd option.
Type : string
Default : "utf-8"
Which encoding does the editor use.
Type : string
Default : "marked"
Markdown processor used to generate HTML MIME parts. By default set to marked. The processor must accept markdown text on stdin and output HTML on stdout. A separate signature file is used for the markdown part.
Type : directory-path
Default : "~"
When loading or saving attachment, use this directory path by default.
Type : boolean
Default : true
If a forced quit is detected by astroid, it makes an attempt to save
unsent messages to a draft file if this option is set to true
Type : list
Default : attach
A list of words that astroid checks for in composed messages before sending. If any of these words are in the message and there is no attachment it may be likely that you have forgotten your attachments. Astroid will show you a warning.
Options related to the contents of a mail message and its headers.
Type : string
Default : "Excerpts from %1's message of %2:"
When replying to a message, this line will be inserted before the
message quoted. The placeholder %1 is replace by the authorname of
the message replied to and %2 is replaced by the date of the
message.
Type : boolean
Default : true
When replying to a mailinglist, the reply will go to the sender of the
message instead of to the list, if this option is set to true
Type : string
Default : "Forwarding %1's message of %2:"
Similar to mail.reply.quote_line but for forwarding messages.
Type : string
Default : "inline"
Should messages be forwarded inline or attachment.
Type : list
Default : sent
Astroid assigns these tags to messages it sends. The special value * assigns all the tags that the message being replied to has. You can filter tags by prefixing them with -. For example, sent,*,-attachment applies the tag sent and all tags the message being replied to has except attachment.
Type : string
Default : ""
For all mail message a so called message id header is created. When
this option is filled, the value is used as the domain part in the
message id header.
The default, that is when the option has no value, is to take the
local hostname.
Type : string
Default : ""
In addition to mail.message_id.fqdn there is also a user part in
that message id header. You can specify here what you want in that
header. The default is astroid
There is a section on why these two options can be useful in Customizing-editor
Type : string
Default : "default"
Another header that is put into mail messages is the "User-Agent" header which gives receivers some information about which program was used to assemble the message. The contents of this head can be specified here. When set to the empty string, the "User-Agent" header will be omitted from outgoing messages.
If you specify default, something like this will be sent:
astroid/v0.9.1-47-g44fddc99 (https://github.com/astroidmail/astroid)
which is astroid along with its version and git revision.
Type : integer
Default : 2
The number of seconds astroid will wait after you sent a message,
before actually doing so. This gives you a chance to cancel it if
needed.
If you specify 0 then the message will be sent immediately
Type : bool
Default : false
The mail composition page will automatically be closed after the message has been successfully sent if this is set tot True.
Type : bool
Default : false
format=flowed will be added to the Content-Type header. This indicates that the message content can be re-flowed by the receiver or when quoting the message. The editor you are using should be configured accordingly - otherwise the behavior can result in somewhat weird formatting on the receiver end (#446,f=f).
For Vim you could use something like this if you set format=flowed:
" format=flowed
au FileType mail setlocal tw=72
au FileType mail setlocal fo+=q
au FileType mail setlocal comments+=nb:>
" Rewrap paragraph using <S-q>
map <silent> <S-q> {gq}<Bar>:echo "Rewrapped paragraph"<CR>Astroid has some support for cryptographically signing and/or encrypting your messages. Note that this is different from a mail signature, which is just a piece of text added to your message, while a cryptographic signature signals that you can prove to the receiver of the message that you actually are who you say you are.
Astroid interfaces with GNUpg so these options only make sense if you are using that.
Type : file-path
Default : "gpg2"
The path to your GNUpg executable, or just the name of the program if
it is in your PATH.
Type : boolean
Default : true
This option determines if gpg, the program that does the encryption
and signing, sets the value always_trust in its context.
When it does, key validation is skipped and keys are assumed to be always valid and as such can be used in astroid.
See the gnupg documentation for the details.
Type : boolean
Default : true
This option allows you to turn off both encryption and decryption of GPG encrypted messages. This can be used to ensure against attacks like EFAIL (although we do not think that Astroid is vulnerable to the exploit).
As an interface to notmuch handling searches is a very common option
in astroid. These are the options related to saving those searches for
repeated use.
Type : boolean
Default : false
Determines if astroid show the saved searches when starting up. Instead of the first startup query it shows the screen with your saved search and the configured search history.
Note that if you set this to false and you have no startup queries configured, astroid will start up with a blank screen, which may be confusing, but it will be fully functional.
Type : boolean
Default : true
Save a list of performed searches when set to true
Type : integer
Default : 15
How many searches should we show in the list. If you set this, show them all.
Type : integer
Default : 1000
Place an upper limit on how many searches astroid should save.
You can have multiple account definitions in astroid. Each account
gets a section in the config file under its name. In the description
of the options this is represented by [accountname]
The defaults listed for these options are for the charlie demo
account created on first use of astroid. You will need to change the
accounts section to have your accounts listed.
Type : string
Default : "Charlie Root"
The name which you want to associate with the account, it will be used in the from address.
Type : string
Default : "root@localhost"
The email-address of the account, also used in the from address.
Type : string
Default : ""
Which gpg key is associated with this account. By specifying this, astroid can sign and encrypt your messages.
Type : boolean
Default : false
Should astroid always sign your messages?
Type : string
Default : "msmtp -i -t"
What is the exact commandline to use when sending a message. This is important to get right. See also Astroid-setup
Type : boolean
Default : true
Is this the default account? This is only relevant if there is more than one account configured.
Type : boolean
Default : true
Should astroid save sent messages somewhere? You probably want this
set to true and configure the next option.
Another option is to configure your MTA (msmtp, postfix etc.) to do some
magic to messages being sent out. For example, postfix has a
always_bcc option which takes an email address; it will send a copy
of all outgoing messages to that address.
Type : directory-path
Default : /home/root/Mail/sent/cur/
This is the directory where astroid will save the sent messages
to. Note that the end of the directory ends here in /cur/ which is a
Maildir specific thing.
Type : list
Default : sent
The special value * assigns all the tags that the message being replied to has. You can filter tags by prefixing them with -. For example, foo,*,-attachment applies the tag foo and all tags the message being replied to has except attachment.
Type : directory-path
Default : /home/root/Mail/drafts/
Similar to save_sent_to this is the path where draft messages are
saved. Note that here the end does not contain /cur/ which in many
cases has the effect that programs like mbsync will not sync your
draft messages back to an IMAP server for example.
Type : file-path
Default : ""
The location of the file which holds the message signature associated with this account.
Type : file-path
Default : ""
The location of the file which holds the mardown version of the message signature associated
with this account. If no markdown signature file is specified, the HTML part will will not have a signature unless it is attached. Only signature_file will have effect if signature_attach is true.
Type : boolean
Default : true
Should the signature be inserted by default by astroid?
Type : boolean
Default : false
Signatures can be inserted into the message as plain contents or attached to the message as a separate part. It's fairly common to not attach a signature (note: this is not a cryptographical signature as mentioned before) but to just append it to the message.
Type : boolean
Default : false
A toggle that decides how a signature is added to a message. If the
value is "true" then the signature will be separate from the message
content and have the defacto standard signature separator -- on its
own line between the message and the signature.
If the value is "false" then the signature will be appended to the message
without separator line.
The advantage of the separator line is that many mail programs use it to show the
message and the signature in a different way, or hide it entirely
This option is only relevant for inline signatures. If you have configured astroid to have your signature as attachment, this option has no effect
A notmuch query used to select this account as sender when replying or forwarding, if the original message matches the specified query. Blank means no query. If no query is specified, first any of your account emails that are present in any of the From, To, Cc, or Bcc fields are used. If none matches, the default account is used.
Options which don't fit under any of the other sections.
Type : integer
Default : 60
Astroid can poll the mail store for new and changed messages
automatically. This options specifies the amount of seconds after
which astroid repeats this. Polling means that a script poll.sh in
the config directory is executed, so you will have to specify there
what is needed in your situation.
Type : bool
Default : false
Will cause all thread-indexes to always be completely refreshed. Useful for detecting deleted threads. Will be slow. Default behavior only updates changed threads and messages, but does not delete threads that have been completely deleted.
Type : string
Default : "xdg-open"
When opening attachment, this command is executed. The filename of the attachment is appended as an argument.
Type : string
Default : see below
The section startup.queries contains lines in the form:
"NAME" : "...notmuch search term or query spec..."
separated by comma's. Each NAME gets a tab in astroid and the query
specified is executed in it, giving a list of threads as found by
notmuch
"startup": {
"queries": {
"INBOX": "tag:unread and not tag:deleted and not tag:muted",
"TODO": "tag:flagged",
"Drafts": "tag:draft"
}
}