Go to the previous, next section.

Kill File

A kill file contains lisp expressions to be applied to a selected newsgroup. The purpose is to mark articles as read on the basis of some set of regexps.

There are two kinds of kill files, global and local. A global kill file is applied to every newsgroup, and a local kill file to a specified newsgroup.

Making a Kill File

A kill file is simply a file of Lisp code that is loaded (i.e., evaluated) while the Summary buffer is current. In order to work properly, the contents of the file must be designed to interact properly with GNUS. To make it easier to write a valid kill file, GNUS provides a general function which does the things users typically want to do in a kill file.

(gnus-kill field regexp &optional command all)

The gnus-kill function performs an action on each article that matches a specified condition.

The two required arguments specify the condition. The argument field specifies a portion of an article; it is either the name of a header field to search, or "", which says to search the entire article body. The argument regexp says what to search for. The condition is this: an article is eligible if the specified portion of the article contains a match for regexp.

The argument command says what to do when an article fits the condition. It is either a valid key sequence in Summary mode, or a Lisp expression which is a list, or nil. A key sequence stands for its command definition in Summary mode; it means to execute that command. A Lisp expression means to evaluate that expression. nil says to mark the article with the character `X'.

If all is omitted or nil, gnus-kill checks only newly arrived articles for meeting the condition. If all is non-nil, it checks all articles.

Here as an example is how to mark all articles whose subjects contain the string `AI':

(gnus-kill "Subject" "AI")

If you want to mark articles with `D' instead of `X', you can use the following expression, which works by executing the d command.

(gnus-kill "Subject" "AI" "d")

The usual aim of a kill file is to delete certain articles. The way to do this is to mark them with `X' and then call gnus-expunge, like this:

(gnus-expunge "X")

gnus-expunge takes one argument, a string containing a number of mark characters, and deletes all the lines that are marked with any of those characters.

It works to use gnus-expunge for the marker `D', but you may not like what it does, because this prevents you from ever rereading an article marked as read in a previous session. That's why the default marker for gnus-kill is `X' rather than `D'.

Searching in the Summary buffer normally ignores case; this includes the searching inside of gnus-kill. If you do not want to ignore the case, set the variable case-fold-search to nil.

After GNUS has finished applying the appropriate kill files, if the newsgroup has no articles left, GNUS exits that newsgroup right away.

Editing Kill Files

You can use these GNUS commands to find a kill file for editing:

Edit a local KILL file applied to the current newsgroup (gnus-summary-edit-local-kill).

Edit a global KILL file applied to all newsgroups (gnus-summary-edit-global-kill).

The same key sequences (M-k and M-K) are available in Group mode also, but the commands that implement them are gnus-group-edit-local-kill and gnus-group-edit-global-kill.

The major mode of these buffers is Kill-File mode, which is like Emacs Lisp mode but with the following additional commands:

C-c C-k C-s
Insert a template of a kill command on subject (gnus-kill-file-kill-by-subject).

C-c C-k C-a
Insert a template of a kill command on author (gnus-kill-file-kill-by-author).

C-c C-a
Evaluate the whole current buffer, but do so with the Summary buffer current (gnus-kill-file-apply-buffer). This is a convenient way to try out a kill file you have been editing.

C-c C-e
Evaluate the sexp before point in current buffer, but do so with the Summary buffer current (gnus-kill-file-apply-last-sexp).

C-c C-c
Save the kill file and then return to the previous buffer (gnus-kill-file-exit).

The effects of C-c C-k C-s and C-c C-k C-a depend on how you began editing the kill file. If you gave the command M-k or M-K while in the Summary buffer, then the article that was current at that time supplies the string to search for, from its own subject or author.

Example of a Kill File

This is a real example of a local kill file for newsgroup `control'.

;; Apply to the newsgroup `control' if the NNTP server is flab.
(if (string-equal gnus-nntp-server "flab")
      (gnus-kill "Subject" "ihave flab\\|sendme")
      (gnus-kill "Subject" "cancel\\|newgroup\\|rmgroup" "d")
      (gnus-expunge "X")))

Names of Kill Files

Kill files are kept in the directory specified by the variable gnus-kill-files-directory; its default value is `~/News'. The variable gnus-kill-file-name specifies the global kill file's name within that directory; the default is `KILL'.

The name of a local kill file is based on the newsgroup's name. If the variable gnus-use-long-file-name is non-nil, then the file name is `newsgroup.KILL'. Otherwise, it is `news/group/KILL', where the subdirectory name is made from the newsgroup name by changing all periods to slashes.

Background Kill Processing

Kill processing can take a long time. If you don't want to wait for it, try background kill processing using the following shell command:

emacs -batch -l gnus -f gnus-batch-kill newsgroups...

where newsgroups are newsgroup names separated by whitespace. `!' preceding a newsgroup name means negation, and `all' specifies all newsgroups not yet decided. These interpretations are the same as the options line of the startup file (see section The Startup File).

Advanced Kill Processing

Internally, applying kills means to run the hook gnus-apply-kill-hook. It is called after the Summary buffer is prepared for a selected newsgroup. The default hook is the function gnus-apply-kill-file which loads a global kill file and a local kill file in this order. A different style of the kill processing can be implemented by customizing this hook.

For example, if you don't have a global kill file, you can use the following hook which applies only a local kill file. This change can save the time for checking the existence of a global kill file.

;; Get rid of the default hook.
(setq gnus-apply-kill-hook nil)
(add-hook 'gnus-apply-kill-hook
  '(lambda ()
     ;; Apply a local kill file.
     (load (gnus-newsgroup-kill-file gnus-newsgroup-name) t nil t)))

(As usual, you can put as many functions as you wish into this hook. What is not usual is the fact that the hook is not initially empty. Therefore, if you don't want the default hook value, you must set the hook variable to nil.)

In contrast, the following example enables only a global kill file.

;; Get rid of the default hook.
(setq gnus-apply-kill-hook nil)
(add-hook 'gnus-apply-kill-hook
  '(lambda ()
     ;; Apply a global kill file.
     (load (gnus-newsgroup-kill-file nil) t nil t)))

Here is an advanced example that drastically reduces the time for applying kill files. This hook does the kill processing directly without loading the kill files.

;; Get rid of the default hook.
(setq gnus-apply-kill-hook nil)
(add-hook 'gnus-apply-kill-hook
  '(lambda ()
     ;; Apply to the newsgroup `control'
     ;; if the NNTP server is flab.
     (and (string-equal gnus-nntp-server "flab")
          (string-equal gnus-newsgroup-name "control")
            (gnus-kill "Subject" "ihave flab\\|sendme")
            (gnus-kill "Subject" "cancel\\|newgroup\\|rmgroup" "d")
            (gnus-expunge "X")))))

Go to the previous, next section.