WeeChat User's Guide ==================== Sébastien Helleu This manual documents WeeChat chat client, it is part of WeeChat. Latest version of this document can be found on this page: http://www.weechat.org/doc [[introduction]] Introduction ------------ WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and light, designed for many operating systems. [[features]] Features ~~~~~~~~ Main features are: * multi-protocols (IRC, Jabber) * multi-servers connection (with SSL, IPv6, proxy) * many GUI: Curses (wxWidgets, Gtk and Qt under development) * small, fast and light * customizable and extensible with plugins and scripts * compliant with IRC RFCs http://www.ietf.org/rfc/rfc1459.txt[1459], http://www.ietf.org/rfc/rfc2810.txt[2810], http://www.ietf.org/rfc/rfc2811.txt[2811], http://www.ietf.org/rfc/rfc2812.txt[2812] and http://www.ietf.org/rfc/rfc2813.txt[2813] * multi-platform (GNU/Linux, *BSD, MacOS X, Windows and other) * 100% GPL, free software WeeChat homepage is here: http://www.weechat.org/ [[pre-requisites]] Pre-requisites ~~~~~~~~~~~~~~ In order to install WeeChat, you need: * a running GNU/Linux system (with compiler tools for source package), or compatible OS * 'root' privileges (to install WeeChat in a system directory) * ncurses library [[install]] Installation ------------ [[binary_packages]] Binary packages ~~~~~~~~~~~~~~~ Binary packages are available for many distributions, including: * Debian (or any Debian compatible distribution): `apt-get install weechat-curses` * Mandriva/RedHat (or any RPM compatible distribution): `rpm -i /path/to/weechat-x.y.z-1.i386.rpm` * Gentoo: `emerge weechat` * Arch Linux: `pacman -S weechat` * Fedora Core: `yum install weechat` * Sourcemage: `cast weechat` Some additional packages may be useful, like weechat-plugins. For other distributions, please look at your manual for installation instructions. [[source_package]] Source package ~~~~~~~~~~~~~~ WeeChat can be compiled with cmake or autotools (cmake is recommended way). [[dependencies]] Dependencies ^^^^^^^^^^^^ Following table shows list of packages that are required or optional to compile WeeChat. [width="80%",cols="4,^2,13",options="header"] |======================================== | Package ^(1)^ | Required | Feature | cmake | *yes* | build (autotools still possible, but cmake is recommended) | libncursesw5-dev ^(2)^ | *yes* | ncurses interface | libgcrypt11-dev | no | SASL authentication with IRC server using DH-BLOWFISH mechanism | libgnutls-dev | no | SSL connection to IRC server | libaspell-dev | no | aspell plugin | libperl-dev | no | perl plugin | python-dev | no | python plugin | ruby1.8-dev | no | ruby plugin | liblua5.1-0-dev | no | lua plugin | tcl-dev (>= 8.5) | no | tcl plugin | asciidoc (>= 8.5.0) | no | build documentation (HTML files) | source-highlight | no | syntax highlight for sources in HTML documentation |======================================== [NOTE] ^(1)^ Name comes from the Debian GNU/Linux distribution, versions and package names may be different in different distributions and versions. + ^(2)^ WeeChat can compile with libncurses5-dev, but it is *NOT* recommended (you will have display bugs with wide chars). [[compile_with_cmake]] Compile with cmake ^^^^^^^^^^^^^^^^^^ * Installation in system directories (requires 'root' privileges): ---------------------------------------- $ mkdir build $ cd build $ cmake .. $ make % make install (as root) ---------------------------------------- * Installation in custom directory: ---------------------------------------- $ mkdir build $ cd build $ cmake .. -DPREFIX=/path/to/directory $ make $ make install ---------------------------------------- [[compile_with_autotools]] Compile with autotools ^^^^^^^^^^^^^^^^^^^^^^ * Installation in system directories (requires 'root' privileges): ---------------------------------------- $ ./configure $ make % make install (as root) ---------------------------------------- * Installation in custom directory: ---------------------------------------- $ ./configure --prefix=/path/to/directory $ make $ make install ---------------------------------------- [[git_sources]] Git sources ~~~~~~~~~~~ Warning: GIT sources are for advanced users: it may not compile or not be stable. You're warned! To get GIT sources, issue this command: ---------------------------------------- $ git clone git://git.sv.gnu.org/weechat.git ---------------------------------------- If you're using autotools (and not cmake), execute this script: ---------------------------------------- $ ./autogen.sh ---------------------------------------- Then follow instructions for source package (see <>). [[report_crashes]] Report crashes ~~~~~~~~~~~~~~ If you experienced crashes, or if you want to report any future WeeChat crash, you have to: * compile it with debug info (or install binary package with debug info) * enable 'core' files on your system * install gdb [[debug_info]] Debug info ^^^^^^^^^^ If you're compiling with cmake: ---------------------------------------- $ cmake .. -DCMAKE_BUILD_TYPE=Debug ---------------------------------------- If you're compiling with autotools, debug is default (`--with-debug=1`). If you installed a binary package, then install package 'weechat-dbg'. [[core_files]] Core files ^^^^^^^^^^ To enable 'core' files, you have to use `ulimit` command. For example under Linux with 'bash' shell, add this line to your `~/.bashrc`: ---------------------------------------- ulimit -c unlimited ---------------------------------------- Or max size: ---------------------------------------- ulimit -c 200000 ---------------------------------------- [[gdb_backtrace]] Get backtrace with gdb ^^^^^^^^^^^^^^^^^^^^^^ When WeeChat crashes, your system will create a file 'core' or 'core.12345' ('12345' is process id). This file is created in directory where you have run WeeChat (this is *not* directory where WeeChat is installed!). For example if 'weechat-curses' is installed in '/usr/bin/' and 'core' file is in '/home/xxx/', then run gdb with this command: ---------------------------------------- gdb /usr/bin/weechat-curses /home/xxx/core ---------------------------------------- [NOTE] If you installed binary package 'weechat-dbg' (for example under Debian), then you can use this path for WeeChat binary: '/usr/lib/debug/usr/bin/weechat-curses' Then under gdb, use command `bt full` to display backtrace. You will see something like that: ---------------------------------------- (gdb) bt full #0 0x00007f9dfb04a465 in raise () from /lib/libc.so.6 #1 0x00007f9dfb04b8e6 in abort () from /lib/libc.so.6 #2 0x0000000000437f66 in weechat_shutdown (return_code=1, crash=1) at /some_path/src/core/weechat.c:351 #3 #4 0x000000000044cb24 in hook_process_timer_cb (arg_hook_process=0x254eb90, remaining_calls=) at /some_path/src/core/wee-hook.c:1364 hook_process = 0x254eb90 status = #5 0x000000000044cc7d in hook_timer_exec () at /some_path/src/core/wee-hook.c:1025 tv_time = {tv_sec = 1272693881, tv_usec = 212665} ptr_hook = 0x2811f40 next_hook = 0x0 #6 0x000000000041b5b0 in gui_main_loop () at /some_path/src/gui/curses/gui-curses-main.c:319 hook_fd_keyboard = 0x173b600 tv_timeout = {tv_sec = 0, tv_usec = 0} read_fds = {fds_bits = {0 }} write_fds = {fds_bits = {0 }} except_fds = {fds_bits = {0 }} max_fd = ---------------------------------------- You must report this trace to developers, and tell them what action caused this crash. Thank you for your help! [[usage]] Usage ----- [[running_weechat]] Running WeeChat ~~~~~~~~~~~~~~~ Command line arguments: -a, --no-connect:: Disable auto-connect to servers when WeeChat is starting -c, --colors:: Display default colors in terminal -d, --dir 'path':: Set path as home for WeeChat (used for configuration files, logs, user plugins and scripts), default value is '~/.weechat' (note: directory is created if not found by WeeChat) -h, --help:: Display help -k, --keys:: Display WeeChat default keys -l, --license:: Display WeeChat license -p, --no-plugin:: Disable plugins auto-load -s, --no-script:: Disable scripts auto-load -v, --version:: Display WeeChat version plugin:option:: Option for plugin (see doc for each plugin) To start WeeChat, issue this command: ---------------------------------------- $ weechat-curses ---------------------------------------- When you run WeeChat for the first time, a default configuration file is created, with default options. The default configuration file is: '~/.weechat/weechat.conf'. You can edit this file at your convenience to configure WeeChat or you can set parameters with `/set` command in WeeChat (see <>). [[screen_layout]] Screen layout ~~~~~~~~~~~~~ Example of terminal with WeeChat: ........................................ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │Welcome to #test, this is a test channel │ │12:52:27 --> | flashy (n=flashcod@hellix.flashtux.org) has joined #test │@ChanServ │ │12:52:27 -- | Nicks #test: [@ChanServ @flashy +_FlashB0t joe mike] │@flashy │ │12:52:27 -- | Channel #test: 5 nicks (2 ops, 0 halfop, 1 voice, 2 normal) │+_FlashB0t│ │12:52:27 -- | Channel created on Tue Jan 27 06:30:17 2009 │joe │ │12:54:15 flashy | hey! │mike │ │12:55:01 joe | hi flashy! │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │[12:55] [4] [irc/freenode] 3:#test(+n){5}* [Act: 4,2] │ │[flashy] hi joe!█ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ ........................................ Screen is composed by following areas: * chat area (middle of screen) with chat lines, and for each line: ** time ** prefix (before "|") ** message (after "|") * bars around chat area, default bars are: ** 'title' bar, above chat area ** 'status' bar, below chat area ** 'input' bar, below status bar ** 'nicklist' bar, on the right Bar 'status' has following default items: [width="100%",cols="^3,^3l,10",options="header"] |======================================== | Item | Example | Description | time | [12:55] | time | buffer_count | [4] | number of opened buffers | buffer_plugin | [irc/freenode] | plugin of current buffer (irc plugin can add IRC server name used by buffer) | buffer_number | 3 | current buffer number | buffer_name | #test(+n) | current buffer name | buffer_nicklist_count | {5} | number of nicks in nicklist | buffer_filter | * | filtering indicator: `*` means some lines are filtered (hidden), empty value means all lines are displayed | lag | [Lag: 2.5] | lag indicator, in seconds (hidden if lag is low) | hotlist | [Act: 4,2] | list of buffers with activity (unread messages) | completion | abc(2) def(5) | list of words for completion, with number of possible completions for each word | scroll | -MORE(50)- | scroll indicator, with number of lines below last line displayed |======================================== Bar 'input' has following default items: [width="100%",cols="^3,^6l,8",options="header"] |======================================== | Item | Example | Description | input_paste | [Paste 7 lines ? [ctrl-Y] Yes [ctrl-N] No] | question to user for pasting lines | input_prompt | [nick] | input prompt (nick for irc plugin) | away | (away) | away indicator | input_search | [Text search] | text search indicator | input_text | bla bla... | input text |======================================== [[key_bindings]] Default key bindings ~~~~~~~~~~~~~~~~~~~~ // 'C-' = ctrl, 'A-' = alt, 'S-' = shift [[key_bindings_command_line]] Keys for command line ^^^^^^^^^^^^^^^^^^^^^ [width="100%",cols="^.^3,.^10,.^5m",options="header"] |======================================== | Key | Description | Command | @k(←) .2+| Go to previous char in command line .2+| /input move_previous_char | @k(C-)@k(b) | @k(→) .2+| Go to next char in command line .2+| /input move_next_char | @k(C-)@k(f) | @k(C-)@k(←) .2+| Go to previous word in command line .2+| /input move_previous_word | @k(A-)@k(b) | @k(C-)@k(→) .2+| Go to next word in command line .2+| /input move_next_word | @k(A-)@k(f) | @k(Home) .2+| Go to the beginning of command line .2+| /input move_beginning_of_line | @k(C-)@k(a) | @k(End) .2+| Go to the end of command line .2+| /input move_end_of_line | @k(C-)@k(e) | @k(C-)@k(c) , @k(b) | Insert code for bold text | /input insert \x02 | @k(C-)@k(c) , @k(c) | Insert code for colored text | /input insert \x03 | @k(C-)@k(c) , @k(i) | Insert code for italic text | /input insert \x1D | @k(C-)@k(c) , @k(o) | Insert code for color reset | /input insert \x0F | @k(C-)@k(c) , @k(r) | Insert code for reverse color | /input insert \x12 | @k(C-)@k(c) , @k(u) | Insert code for underlined text | /input insert \x15 | @k(Del) .2+| Delete next char in command line .2+| /input delete_next_char | @k(C-)@k(d) | @k(Backsp.) .2+| Delete previous char in command line .2+| /input delete_previous_char | @k(C-)@k(h) | @k(C-)@k(k) | Delete from cursor until end of command line (deleted string is copied to clipboard) | /input delete_end_of_line | @k(C-)@k(r) | Search for text in buffer history (two times: search exact text), @k(↑): previous, @k(↓): next, @k(Enter): stop | /input search_text | @k(C-)@k(t) | Transpose chars | /input transpose_chars | @k(C-)@k(u) | Delete from cursor until beginning of command line (deleted string is copied to clipboard) | /input delete_beginning_of_line | @k(C-)@k(w) | Delete previous word of command line (deleted string is copied to clipboard) | /input delete_previous_word | @k(C-)@k(y) | Paste clipboard content | /input clipboard_paste | @k(C-)@k(_) | Undo last action on command line | /input undo | @k(A-)@k(_) | Redo last action on command line | /input redo | @k(Tab) | Complete command or nick (@k(Tab) again: find next completion) | /input complete_next | @k(S-)@k(Tab) | Without completion: do a partial completion, with pending completion: complete with previous completion | /input complete_previous | @k(Enter) .3+| Execute command or send message (in search mode: stop search) .3+| /input return | @k(C-)@k(j) | @k(C-)@k(m) | @k(↑) | Call previous command/message (in search mode: search up) | /input history_previous | @k(↓) | Call next command/message (in search mode: search down) | /input history_next | @k(C-)@k(↑) | Call previous command/message in global history (common for all buffers) | /input history_global_previous | @k(C-)@k(↓) | Call next command/message in global history (common for all buffers) | /input history_global_next | @k(A-)@k(d) | Delete next word in command line (deleted string is copied to clipboard) | /input delete_next_word | @k(A-)@k(k) | Grab a key and insert its code (and command bound if key exists) in command line | /input grab_key_command | @k(A-)@k(r) | Delete entire command line | /input delete_line |======================================== [[key_bindings_buffers_windows]] Keys for buffers / windows ^^^^^^^^^^^^^^^^^^^^^^^^^^ [width="100%",cols="^.^3,.^10,.^5m",options="header"] |======================================== | Key | Description | Command | @k(C-)@k(l) | Redraw whole window | /window refresh | @k(C-)@k(s) , @k(C-)@k(u) | Set unread marker on all buffers | /input set_unread | @k(C-)@k(x) | Switch current buffer if buffers are attached with same number | /input switch_active_buffer | @k(PgUp) | Scroll up one page in buffer history | /window page_up | @k(PgDn) | Scroll down one page in buffer history | /window page_down | @k(A-)@k(PgUp) | Scroll up a few lines in buffer history | /window scroll_up | @k(A-)@k(PgDn) | Scroll down a few lines in buffer history | /window scroll_down | @k(A-)@k(Home) | Scroll to top of buffer | /window scroll_top | @k(A-)@k(End) | Scroll to bottom of buffer | /window scroll_bottom | @k(A-)@k(←) .4+| Switch to previous buffer .4+| /buffer -1 | @k(A-)@k(↑) | @k(C-)@k(p) | @k(F5) | @k(A-)@k(→) .4+| Switch to next buffer .4+| /buffer +1 | @k(A-)@k(↓) | @k(C-)@k(n) | @k(F6) | @k(F7) | Switch to previous window | /window -1 | @k(F8) | Switch to next window | /window +1 | @k(F9) | Scroll buffer's title on the left | /bar scroll title * x-50% | @k(F10) | Scroll buffer's title on the right | /bar scroll title * x+50% | @k(F11) | Scroll up one page in nicklist | /bar scroll nicklist * y-100% | @k(F12) | Scroll down one page in nicklist | /bar scroll nicklist * y+100% | @k(A-)@k(F11) | Go to the beginning of nicklist | /bar scroll nicklist * yb | @k(A-)@k(F12) | Go to the end of nicklist | /bar scroll nicklist * ye | @k(A-)@k(a) | Switch to next buffer with activity (with priority: highlight, message, other) | /input jump_smart | @k(A-)@k(j) , @k(A-)@k(l) | Switch to last buffer | /input jump_last_buffer | @k(A-)@k(j) , @k(A-)@k(r) | Switch to IRC raw buffer | /server raw | @k(A-)@k(j) , @k(A-)@k(s) | Switch to IRC server buffer | /server jump | @k(A-)@k(0...9) | Switch to buffer by number (0 = 10) | /buffer *N | @k(A-)@k(j) , @k(01...99) | Switch to buffer by number | /buffer NN | @k(A-)@k(n) | Scroll to next highlight | /window scroll_next_highlight | @k(A-)@k(p) | Scroll to previous highlight | /window scroll_previous_highlight | @k(A-)@k(u) | Scroll to first unread line in buffer | /input scroll_unread | @k(A-)@k(w) , @k(A-)@k(↑) | Switch to window above | /window up | @k(A-)@k(w) , @k(A-)@k(↓) | Switch to window below | /window down | @k(A-)@k(w) , @k(A-)@k(←) | Switch to window on the left | /window left | @k(A-)@k(w) , @k(A-)@k(→) | Switch to window on the right | /window right | @k(A-)@k(z) | Zoom on current window (@k(A-)@k(z) again: restore initial windows state, before zoom) | /window zoom | @k(A-)@k(<) | Switch to previous buffer in list of visited buffers | /input jump_previously_visited_buffer | @k(A-)@k(>) | Switch to next buffer in list of visited buffers | /input jump_next_visited_buffer |======================================== [[key_bindings_other]] Other keys ^^^^^^^^^^ [width="100%",cols="^.^3,.^10,.^5m",options="header"] |======================================== | Key | Description | Command | @k(A-)@k(h) | Clear hotlist (activity notification on other buffers) | /input hotlist_clear | @k(A-)@k(=) | Toggle filters on/off | /filter toggle |======================================== [[command_line]] Command line ~~~~~~~~~~~~ WeeChat command line (at the bottom of window) lets you execute commands or send text to buffer. [[command_line_syntax]] Syntax ^^^^^^ Commands begin with "/" char, followed by name of command. For example, to see list of all options: ---------------------------------------- /set ---------------------------------------- Text sent to a buffer is any text that does not begin with "/" char. For example, to send text 'hello' on current buffer: ---------------------------------------- hello ---------------------------------------- However, it is possible to start with "/" char, by adding another. For example, to send text '/set' on current buffer: ---------------------------------------- //set ---------------------------------------- [[command_line_colors]] Color codes ^^^^^^^^^^^ For some plugins like IRC, you can use color codes and attributes, as follow (press @k(C-)@k(c) then following letter, with optional value): @k(C-)@k(c) , @k(b):: bold text @k(C-)@k(c) , @k(c) , @k(xx):: text color `xx` (see list of colors below) @k(C-)@k(c) , @k(c) , @k(xx,yy):: text color `xx` and background `yy` (see list of colors below) @k(C-)@k(c) , @k(o):: disable color and attributes @k(C-)@k(c) , @k(r):: reverse video (revert text color with background) @k(C-)@k(c) , @k(u):: underlined text [NOTE] The same code (without number for @k(C-)@k(c) , @k(c)) may be used to stop the attribute. Color codes for @k(C-)@k(c) , @k(c) are: [width="50%",cols="^1m,3,3",options="header"] |======================================== | Code | IRC | WeeChat (curses) | 00 | white | white | 01 | black | black | 02 | dark blue | blue | 03 | dark green | green | 04 | light red | lightred | 05 | dark red | red | 06 | magenta | magenta | 07 | orange | brown | 08 | yellow | yellow | 09 | light green | lightgreen | 10 | cyan | cyan | 11 | light cyan | lightcyan | 12 | light blue | lightblue | 13 | light magenta | lightmagenta | 14 | gray | gray | 15 | light gray | white |======================================== Example: display of "hello everybody!" with "hello" in light blue bold and "everybody" in light red underlined: ---------------------------------------- ^Cc12^Cbhello ^Cb^Cc04^Cueverybody^Cu^Cc! ---------------------------------------- [[weechat_options]] WeeChat options (weechat.conf) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ include::autogen/user/weechat_options.txt[] [[weechat_commands]] WeeChat commands ~~~~~~~~~~~~~~~~ include::autogen/user/weechat_commands.txt[] [[colors]] Colors ~~~~~~ WeeChat can use up to 256 color pairs to display text in bars and chat area (your terminal must support 256 colors to use them in WeeChat). According to value of 'TERM' environment variable, you may have following limits for colors in WeeChat: [width="50%",cols="8,>2,>2",options="header"] |======================================== | $TERM | Colors | Pairs ^(1)^ | "rxvt-unicode", "xterm",... | 88 | 256 | "rxvt-256color", "xterm-256color",... | 256 | 32767 | "screen" | 8 | 64 | "screen-256color" | 256 | 32767 |======================================== [NOTE] ^(1)^ Even if your terminal supports more than 256 pairs, only 256 pairs can be used in WeeChat, because of a ncurses limitation. You can run `weechat-curses --colors` or use command `/color` in WeeChat to display limits for your environment. Some recommended values for 'TERM' if you want 256 colors: * under screen: 'screen-256color' * outside screen: 'xterm-256color', 'rxvt-256color', 'putty-256color',... [NOTE] You may have to install package "ncurses-term" to use these values in 'TERM' variable. If you are using screen, you can add this line to your '~/.screenrc': ---------------------------------------- term screen-256color ---------------------------------------- If your 'TERM' variable has wrong value and that WeeChat is already running, don't panic! You can change it without restarting, thanks to script 'shell.py': ---------------------------------------- /shell setenv TERM=screen-256color /upgrade ---------------------------------------- [[colors_basic]] Basic colors ^^^^^^^^^^^^ Basic colors in WeeChat are: [width="50%",cols="^3m,8",options="header"] |======================================== | Name | Color | default | default terminal color (transparent for background) | black | black | darkgray | dark gray | red | dark red | lightred | light red | green | dark green | lightgreen | light green | brown | brown | yellow | yellow | blue | dark blue | lightblue | light blue | magenta | dark magenta | lightmagenta | light magenta | cyan | dark cyan | lightcyan | light cyan | gray | gray | white | white |======================================== [[colors_extended]] Extended colors ^^^^^^^^^^^^^^^ WeeChat dynamically allocates color pairs when colors are used on screen (to display buffers and bars). In addition to basic colors, you can use a color number between 1 and the limit of your terminal. Use command `/color` to see current colors and limits. With 'alt+c' you can temporarily switch to terminal colors to choose a color. For example if you want to display time in orange in buffer, do: ---------------------------------------- /set weechat.color.chat_time 214 ---------------------------------------- Or if you want a very dark green background for status bar: ---------------------------------------- /set weechat.bar.status.color_bg 22 ---------------------------------------- [[colors_aliases]] Aliases ^^^^^^^ You can add color aliases with command `/color alias` and then use this alias in any color option. For example: ---------------------------------------- /color alias 214 orange /set weechat.color.chat_delimiters orange ---------------------------------------- [[colors_attributes]] Attributes ^^^^^^^^^^ It is possible to use some attributes for colors. One or more attributes can be added before color name or number: * "*": bold text * "!": reverse video * "_": underlined text For example if you want self nick as white underlined, do: ---------------------------------------- /set weechat.color.chat_nick_self _white ---------------------------------------- Or if you want time in status bar as orange underlined with bold: ---------------------------------------- /set weechat.color.status_time *_214 ---------------------------------------- To use an attribute with default terminal color (-1), you must use a number greater than last terminal color, for example max color in WeeChat: 99999. Example of bold with terminal foreground color: ---------------------------------------- /set weechat.color.status_time *99999 ---------------------------------------- [[plugins]] Plugins ------- To learn more about plugin or script development (through API), please read 'WeeChat Plugin API Reference' or 'WeeChat Scripting Guide'. [[plugins_in_weechat]] Plugins in WeeChat ~~~~~~~~~~~~~~~~~~ A plugin is dynamic library, written in C and compiled, which is loaded by WeeChat. Under GNU/Linux, the file has ".so" extension, ".dll" under Windows. Plugins found are automatically loaded when WeeChat is starting, and it is possible to load or unload plugins while WeeChat is running. It's important to make difference between a 'plugin' and a 'script': a 'plugin' is a binary file compiled and loaded with command `/plugin`, whereas a 'script' is a text file loaded with a plugin like 'perl' with command `/perl`. You can use command `/plugin` to load/unload a plugin, or list all loaded plugins. When a plugin is unloaded, all buffers created by this plugin are automatically closed. Examples to load, unload or list plugins: ---------------------------------------- /plugin load irc /plugin unload irc /plugin list ---------------------------------------- Default plugins are: [width="50%",cols="^1,5",options="header"] |======================================== | Plugin | Description | alias | Define alias for commands | aspell | Spell checking for command line | charset | Charset decoding/encoding for buffers | demo | Demo plugin (not compiled by default) | fifo | FIFO pipe used to remotely send commands to WeeChat | irc | IRC chat protocol | logger | Log buffers to files | relay | Relay data via network (IRC proxy) | rmodifier | Alter modifier strings with regular expressions | perl | Perl scripting API | python | Python scripting API | ruby | Ruby scripting API | lua | Lua scripting API | tcl | Tcl scripting API | xfer | File transfer and direct chat |======================================== [[alias_plugin]] Alias plugin ~~~~~~~~~~~~ Alias plugin lets you create alias for commands (from WeeChat or other plugins). [[alias_commands]] Commands ^^^^^^^^ include::autogen/user/alias_commands.txt[] [[aspell_plugin]] Aspell plugin ~~~~~~~~~~~~ Aspell plugin lets you check spelling in command line. It is possible to use many languages by buffer. [[aspell_options]] Options (aspell.conf) ^^^^^^^^^^^^^^^^^^^^^ include::autogen/user/aspell_options.txt[] [[aspell_commands]] Commands ^^^^^^^^ include::autogen/user/aspell_commands.txt[] [[charset_plugin]] Charset plugin ~~~~~~~~~~~~~~ Charset plugin lets you decode or encode data using charsets. There is default charset for decode/encode, and specific charsets for buffers (or group of buffers). This plugin is optional, but recommended: if it's not loaded, WeeChat can only read/write UTF-8 data. Charset plugin should be autoloaded by WeeChat. To be sure plugin is loaded, try: ---------------------------------------- /charset ---------------------------------------- If command is not found, then load plugin with command: ---------------------------------------- /plugin load charset ---------------------------------------- If plugin is not found, then you should compile again WeeChat with plugins and Charset support. When Charset plugin starts, it displays terminal and internal charsets. Terminal charset depends on your locale, and internal is UTF-8. For example: ........................................ charset: terminal: ISO-8859-15, internal: UTF-8 ........................................ [[charset_options]] Options (charset.conf) ^^^^^^^^^^^^^^^^^^^^^^ include::autogen/user/charset_options.txt[] [[charset_commands]] Commands ^^^^^^^^ include::autogen/user/charset_commands.txt[] [[charset_set]] Set charset ^^^^^^^^^^^ To set global decode and encode charsets, use command `/set`. For example: ---------------------------------------- /set charset.default.decode ISO-8859-15 /set charset.default.encode ISO-8859-15 ---------------------------------------- If global decode charset is not set (for example during first load of Charset plugin), it will be automatically set to terminal charset (if it's different from UTF-8), or by default to 'ISO-8859-1'. Default encode value is empty, so it sends by default with internal charset (UTF-8). To set IRC server charset, use command `/charset` on server buffer. If you give only charset, then it will set decoding and encoding values. For example: ---------------------------------------- /charset ISO-8859-15 ---------------------------------------- It's equivalent to: ---------------------------------------- /charset decode ISO-8859-15 /charset encode ISO-8859-15 ---------------------------------------- To set IRC channel (or private) charset, use same commands as server, but on channel (or private) buffer. To see all charsets used, use following command: ---------------------------------------- /set charset.* ---------------------------------------- [[charset_troubleshooting]] Troubleshooting ^^^^^^^^^^^^^^^ For any problem with charsets, please look at 'WeeChat FAQ'. [[fifo_plugin]] Fifo plugin ~~~~~~~~~~~ You can remote control WeeChat, by sending commands or text to a FIFO pipe (if option "plugins.var.fifo.fifo" is enabled, it is by default). The FIFO pipe is located in '~/.weechat/' and is called 'weechat_fifo_xxxx' (where 'xxxx' is the process ID (PID) of running WeeChat). Syntax for the FIFO pipe commands/text is one of following: ........................................ plugin.buffer *text or command here *text or command here ........................................ Some examples: * nick change on IRC server freenode to "newnick": ---------------------------------------- $ echo 'irc.server.freenode */nick newnick' >~/.weechat/weechat_fifo_12345 ---------------------------------------- * display text on IRC #weechat channel: ---------------------------------------- $ echo 'irc.freenode.#weechat *hello!' >~/.weechat/weechat_fifo_12345 ---------------------------------------- * display text on current buffer: ---------------------------------------- $ echo '*hello!' >~/.weechat/weechat_fifo_12345 ---------------------------------------- * send two commands to unload/reload Perl scripts (you have to separate them with "\n"): ---------------------------------------- $ echo -e '*/perl unload\n*/perl autoload' >~/.weechat/weechat_fifo_12345 ---------------------------------------- You can write a script to send command to all running WeeChat at same time, for example: [source,shell] ---------------------------------------- #!/bin/sh if [ $# -eq 1 ]; then for fifo in ~/.weechat/weechat_fifo_* do echo -e "$1" >$fifo done fi ---------------------------------------- If the script is called "auto_weechat_command", you can run it with: ---------------------------------------- $ ./auto_weechat_command 'irc.freenode.#weechat *hello' ---------------------------------------- [[irc_plugin]] IRC plugin ~~~~~~~~~~ The IRC plugin is designed to chat through IRC protocol with other people. It is multi-servers, and offers all supported IRC commands including DCC chat and file transfer (via xfer plugin, see <>). [[irc_command_line_options]] Command line options ^^^^^^^^^^^^^^^^^^^^ It is possible to give URL for one or many IRC servers, as follow: ---------------------------------------- irc[6][s]://[pseudo[:mot_passe]@]irc.example.org[:port][/channel][,channel[...] ---------------------------------------- Example to join '#weechat' and '#toto' on server 'irc.freenode.net' server, default port (6667), with nick 'nono': ---------------------------------------- $ weechat-curses irc://nono@irc.freenode.net/#weechat,#toto ---------------------------------------- [[irc_options]] Options (irc.conf) ^^^^^^^^^^^^^^^^^^ include::autogen/user/irc_options.txt[] [[irc_commands]] Commands ^^^^^^^^ include::autogen/user/irc_commands.txt[] [[irc_ssl_certificates]] SSL certificates ^^^^^^^^^^^^^^^^ When connecting to IRC server with SSL, WeeChat checks by default that the connection is fully trusted. Some options are used to control SSL connection: weechat.network.gnutls_ca_file:: path to file with certificate authorities (by default: "%h/ssl/CAs.pem") irc.server.xxx.ssl_cert:: SSL certificate file used to automatically identify your nick (for example CertFP on oftc, see below) irc.server.xxx.ssl_dhkey_size:: size of the key used during the Diffie-Hellman Key Exchange (by default: 2048) irc.server.xxx.ssl_verify:: check that the SSL connection is fully trusted (on by default) [NOTE] Option "ssl_verify" is on by default, so verification is strict and may fail, even if it was ok with versions prior to 0.3.1. [[irc_connect_oftc_with_certificate]] First example: connect to oftc and check certificate ++++++++++++++++++++++++++++++++++++++++++++++++++++ * Import certificate in shell: ---------------------------------------- $ mkdir ~/.weechat/ssl $ wget -O ~/.weechat/ssl/CAs.pem http://www.spi-inc.org/secretary/spi-cacert.crt ---------------------------------------- Note: it is possible to concatenate many certificates in file CAs.pem. * In WeeChat, with "oftc" server already created: ---------------------------------------- /connect oftc ---------------------------------------- [[irc_connect_oftc_with_certfp]] Second example: connect to oftc using CertFP ++++++++++++++++++++++++++++++++++++++++++++ * Create certificate in shell: ---------------------------------------- $ openssl req -nodes -newkey rsa:2048 -keyout nick.key -x509 -days 365 -out nick.cer $ cat nick.cer nick.key > ~/.weechat/ssl/nick.pem ---------------------------------------- * In WeeChat, with "oftc" server already created: ---------------------------------------- /set irc.server.oftc.ssl_cert "%h/ssl/nick.pem" /connect oftc /msg nickserv cert add ---------------------------------------- For more information, look at http://www.oftc.net/oftc/NickServ/CertFP [[irc_smart_filter_join_part_quit]] Smart filter for join/part/quit messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A smart filter is available to filter join/part/quit messages when nick did not say something during past X minutes on channel. Smart filter is enabled by default, but you must add a filter to hide lines on buffers, for example: ---------------------------------------- /filter add irc_smart * irc_smart_filter * ---------------------------------------- It is possible to create filter for one channel only or channels beginning with same name (see `/help filter`): ---------------------------------------- /filter add irc_smart_weechat irc.freenode.#weechat irc_smart_filter * /filter add irc_smart_weechats irc.freenode.#weechat* irc_smart_filter * ---------------------------------------- You can hide only join or part/quit with following options: ---------------------------------------- /set irc.look.smart_filter_join on /set irc.look.smart_filter_quit on ---------------------------------------- You can setup delay (in minutes): ---------------------------------------- /set irc.look.smart_filter_delay 5 ---------------------------------------- If a nick did not speak during last 5 minutes, its join and/or part/quit will be hidden on channel. [[irc_ctcp_replies]] CTCP replies ^^^^^^^^^^^^ It is possible to customize CTCP replies, or block some CTCP queries (do not reply). For example, to customize reply to CTCP "VERSION", use following command: ---------------------------------------- /set irc.ctcp.version "I'm running WeeChat $version, it rocks!" ---------------------------------------- If you want to block CTCP "VERSION" (do not reply to a query), then set empty string: ---------------------------------------- /set irc.ctcp.version "" ---------------------------------------- Even unknown CTCP can be customized, for example you can reply to CTCP "BLABLA": ---------------------------------------- /set irc.ctcp.blabla "This is my answer to CTCP BLABLA" ---------------------------------------- It is possible to customize CTCP for one server only, using its internal name before CTCP name: ---------------------------------------- /set irc.ctcp.freenode.version "WeeChat $version (for freenode)" ---------------------------------------- If you want to restore standard CTCP reply, then remove option: ---------------------------------------- /unset irc.ctcp.version ---------------------------------------- Following codes can be used in strings and are automatically expanded by WeeChat when replying to CTCP: [width="100%",cols="^2l,4,8l",options="header"] |======================================== | Code | Description | Value/example | $clientinfo | list of supported CTCP | ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION | $version | WeeChat version | 0.3.0 | $compilation | WeeChat compilation date | Sep 13 2009 | $osinfo | info about OS | Linux 2.6.31 / i686 | $site | WeeChat site | http://www.weechat.org | $download | WeeChat site, download page | http://www.weechat.org/download | $time | current date/time | Sun Sep 13 15:48:31 2009 | $username | username on IRC server | nick | $realname | realname on IRC server | My name |======================================== If CTCP options are not defined (by default), CTCP replies are: [width="100%",cols="^2,4l,8l",options="header"] |======================================== | CTCP | Reply format | Example | CLIENTINFO | $clientinfo | ACTION DCC CLIENTINFO FINGER PING SOURCE TIME USERINFO VERSION | FINGER | WeeChat $version | WeeChat 0.3.0 | SOURCE | $download | http://www.weechat.org/download | TIME | $time | Sun Sep 13 15:48:31 2009 | USERINFO | $username ($realname) | nick (My name) | VERSION | WeeChat $version ($compilation) | WeeChat 0.3.0 (Sep 13 2009) |======================================== [[irc_target_buffer]] Target buffer for IRC messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It is possible to customize target buffer for IRC messages (buffer used to display message) with options `irc.msgbuffer.*`. For some IRC messages (see list below), you can use value: current:: current buffer (if it's IRC buffer, or on server buffer by default) private:: private buffer for nick, or current/server buffer if not found (according to option 'irc.look.msgbuffer_fallback') server:: server buffer weechat:: WeeChat "core" buffer When option is not set (default), WeeChat chooses appropriate buffer, commonly server or channel buffer. Non-comprehensive list of IRC messages or alias that you can customize: [width="60%",cols="^1m,^3m,8",options="header"] |======================================== | message | alias | description | error | | error | invite | | invited on a channel | join | | join | kick | | kick | kill | | kill | mode | | mode | notice | | notice | part | | part | quit | | quit | topic | | topic | wallops | | wallops | 221 | | user mode string | 275 | whois | whois (secure connection) | 301 | whois | whois (away) | 303 | | ison | 305 | unaway | unaway | 306 | away | away | 307 | whois | whois (registered nick) | 310 | whois | whois (help mode) | 311 | whois | whois (user) | 312 | whois | whois (server) | 313 | whois | whois (operator) | 314 | whowas | whowas | 315 | who | who (end) | 317 | whois | whois (idle) | 318 | whois | whois (end) | 319 | whois | whois (channels) | 320 | whois | whois (identified user) | 321 | list | list (start) | 322 | list | list (channel) | 323 | list | list (end) | 326 | whois | whois (has oper privs) | 327 | whois | whois (host) | 328 | | channel URL | 329 | | channel creation date | 330 | whois | whois (logged in as) | 331 | | no topic for channel | 332 | | topic of channel | 333 | | infos about topic | 335 | whois | whois (is a bot on) | 338 | whois | whois (host) | 341 | | inviting | 344 | reop | channel reop | 345 | reop | channel reop (end) | 346 | invitelist | invite list | 347 | invitelist | invite list (end) | 348 | exceptionlist | exception list | 349 | exceptionlist | exception list (end) | 351 | | server version | 352 | who | who | 353 | names | list of users on channel | 366 | names | end of /names list | 367 | banlist | ban list | 368 | banlist | end of ban list | 369 | whowas | whowas (end) | 378 | whois | whois (connecting from) | 379 | whois | whois (using modes) | 432 | | erroneous nickname | 433 | | nickname already in use | 438 | | not authorized to change nickname | 671 | whois | whois (secure connection) | 901 | | you are now logged in |======================================== Other numeric commands can be customized as well. Message can be prefixed by server name to be specific to an irc server (for example: `freenode.whois`). Some examples: * display result of `/whois` on private buffer: ---------------------------------------- /set irc.msgbuffer.whois private ---------------------------------------- * restore default buffer for whois (server buffer): ---------------------------------------- /unset irc.msgbuffer.whois ---------------------------------------- * display invitation on current buffer, only for "freenode" server: ---------------------------------------- /set irc.msgbuffer.freenode.invite current ---------------------------------------- * display message "303" (ison) on WeeChat "core" buffer: ---------------------------------------- /set irc.msgbuffer.303 weechat ---------------------------------------- [[logger_plugin]] Logger plugin ~~~~~~~~~~~~~ The Logger plugin lets you save content of buffers to files, with options about what and how it is saved. [[logger_options]] Options (logger.conf) ^^^^^^^^^^^^^^^^^^^^^ include::autogen/user/logger_options.txt[] [[logger_commands]] Commands ^^^^^^^^ include::autogen/user/logger_commands.txt[] [[logger_log_levels]] Log levels ^^^^^^^^^^ Logging is made with a level for each buffer. Default level is 9 (log all messages displayed on buffer). You can change level for one buffer, or a group of buffers. Possible levels are 0 to 9. Zero means "do not log anything" and 9 means "log all messages". Plugins are using different levels for messages displayed. IRC plugin uses following levels: * level 1: message from user (on channel or private) * level 2: nick change (you or someone else) * level 3: any server message (except join/part/quit) * level 4: server message join/part/quit So if you set level 3 for an IRC channel, WeeChat will log all messages, but not join/part/quit. Some examples: * set level 3 for IRC channel #weechat: ---------------------------------------- /set logger.level.irc.freenode.#weechat 3 ---------------------------------------- * set level 3 for freenode server buffer: ---------------------------------------- /set logger.level.irc.server.freenode 3 ---------------------------------------- * set level 3 for all channels on server freenode: ---------------------------------------- /set logger.level.irc.freenode 3 ---------------------------------------- * set level 2 for all IRC buffers: ---------------------------------------- /set logger.level.irc 2 ---------------------------------------- [[logger_filenames_masks]] Filenames masks ^^^^^^^^^^^^^^^ It is possible to define a filename mask for each buffer, and use local buffer variables to build filename. To see local variables for current buffer: ---------------------------------------- /buffer localvar ---------------------------------------- For example, on buffer "irc.freenode.#weechat", WeeChat will search a mask with option name, in this order: ---------------------------------------- logger.mask.irc.freenode.#weechat logger.mask.irc.freenode logger.mask.irc logger.file.mask ---------------------------------------- That means you can have masks specific for some IRC servers ("logger.mask.irc.freenode") or for a plugin ("logger.mask.irc"). [[logger_files_by_date]] Log files by date +++++++++++++++++ To have log files by date, you can use date/time specifiers in mask (see `man strftime` for formats), for example: ---------------------------------------- /set logger.file.mask "%Y/%m/$plugin.$name.weechatlog" ---------------------------------------- You'll have following files: ........................................ ~/.weechat/ |--- logs/ |--- 2010/ |--- 11/ | irc.server.freenode.weechatlog | irc.freenode.#weechat.weechatlog |--- 2010/ |--- 12/ | irc.server.freenode.weechatlog | irc.freenode.#weechat.weechatlog ........................................ [[logger_irc_files_by_server_channel]] IRC log files by server and channel +++++++++++++++++++++++++++++++++++ If you want one directory by IRC server and one file by channel inside: ---------------------------------------- /set logger.mask.irc "irc/$server/$channel.weechatlog" ---------------------------------------- You'll have following files: ........................................ ~/.weechat/ |--- logs/ |--- irc/ |--- freenode/ | freenode.weechatlog | #weechat.weechatlog | #mychan.weechatlog |--- oftc/ | oftc.weechatlog | #chan1.weechatlog | #chan2.weechatlog ........................................ [[relay_plugin]] Relay plugin ~~~~~~~~~~~~ The Relay plugin is used to relay data via network, using different protocols. Currently, only "irc" protocol is supported (IRC proxy). [[relay_options]] Options (relay.conf) ^^^^^^^^^^^^^^^^^^^^ include::autogen/user/relay_options.txt[] [[relay_commands]] Commands ^^^^^^^^ include::autogen/user/relay_commands.txt[] [[relay_irc_proxy]] IRC proxy ^^^^^^^^^ The Relay plugin can act as an IRC proxy: you can define one port by IRC server and use a password for clients. For example: ---------------------------------------- /set relay.network.password "mypass" /relay add irc.freenode 8000 ---------------------------------------- Now you can connect on port 8000 with any IRC client (WeeChat, xchat, irssi, ..), using server password "mypass". You can limit number of allowed clients: ---------------------------------------- /set relay.network.max_clients 1 ---------------------------------------- [[rmodifier_plugin]] Rmodifier plugin ~~~~~~~~~~~~~~~~ The Rmodifier plugin lets you alter modifier strings using regular expressions. Typical use is to hide password when you type them, or when WeeChat saves them in command history. For example, it is possible to replace each char in these passwords by "*". [[rmodifier_options]] Options (rmodifier.conf) ^^^^^^^^^^^^^^^^^^^^^^^^ include::autogen/user/rmodifier_options.txt[] [[rmodifier_commands]] Commands ^^^^^^^^ include::autogen/user/rmodifier_commands.txt[] [[rmodifier_creation]] Rmodifier creation ^^^^^^^^^^^^^^^^^^ A rmodifier consists of three elements: . one or more "modifiers" . a regular expression, to capture "groups" . a string that describes output using number of "groups" captured in regular expression For list of modifiers used by WeeChat or plugins, see 'WeeChat Plugin API Reference', function 'weechat_hook_modifier'. For each captured group, following actions are possible: * keep group as-is (by using group number) * replace all chars in group to hide content (group number + "*") * remove group (if group is not used in string) Example of default rmodifier for command `/oper`: * modifiers: `history_add,input_text_display` ** `history_add`: called when WeeChat stores command in history ** `input_text_display`: called when command line has changed (applies only on display, not content of command line) * regular expression: `^(/oper +\S+ +)(.*)` * groupes: `1,2*` Each time modifiers "history_add" or "input_text_display" are called, regular expression is checked. If string matches, then it is replaced by captured groups, as defined in string with groups. In this example, we keep number 1 as-is, and we replace all chars of group 2 by replacement char defined in configuration (option 'rmodifier.look.hide_char'). If command line contains: `/oper nick password` then display becomes: `/oper nick ********`. [[scripts_plugins]] Scripts plugins ~~~~~~~~~~~~~~~ WeeChat provides 5 scripting plugins: Perl, Python, Ruby, Lua and Tcl. These plugins can load, execute and unload scripts for these languages. For more information about how to write scripts, or WeeChat API for scripts, please read 'WeeChat Scripting Guide'. You can find some scripts for WeeChat here: http://www.weechat.org/scripts [[perl_commands]] Perl commands ^^^^^^^^^^^^^ include::autogen/user/perl_commands.txt[] [[python_commands]] Python commands ^^^^^^^^^^^^^^^ include::autogen/user/python_commands.txt[] [[ruby_commands]] Ruby commands ^^^^^^^^^^^^^ include::autogen/user/ruby_commands.txt[] [[lua_commands]] Lua commands ^^^^^^^^^^^^ include::autogen/user/lua_commands.txt[] [[tcl_commands]] Tcl commands ^^^^^^^^^^^^ include::autogen/user/tcl_commands.txt[] [[xfer_plugin]] Xfer plugin ~~~~~~~~~~~ Xfer plugin brings: * direct chat (between two hosts, without server): for example "DCC Chat" via IRC plugin * file transfer, for example "DCC" via IRC plugin [[xfer_options]] Options (xfer.conf) ^^^^^^^^^^^^^^^^^^^^^ include::autogen/user/xfer_options.txt[] [[xfer_commands]] Commands ^^^^^^^^ include::autogen/user/xfer_commands.txt[] [[authors]] Authors ------- [[developers]] Developers ~~~~~~~~~~ Main developer:: Sébastien Helleu (FlashCode) [[contributors]] Contributors ~~~~~~~~~~~~ Packagers:: Emmanuel Bouthenot (kolter), Julien Louis (ptitlouis), Odin Translations:: Jiri Golembiovsky, soltys, Nils Görs, rettub, Frank Zacharias, Pavel Shevchuk, Elián Hanisch (m4v), Voroskoi, Marco Paolone, Ivan Sichmann Freitas Patches:: Dmitry Kobylin, Rudolf Polzer, Jim Ramsay, Pistos, Gwenn, Dominik Honnef, JD Horelick, Stefano Pigozzi, Gu1ll4um3r0m41n [[support]] Support ------- Before asking for support, be sure you've read documentation and FAQ provided with WeeChat (documentation is this document, if you don't read all lines until this sentence, you can start again!). Ways to get support: * IRC: server 'irc.freenode.net', channels '#weechat' (english) and '#weechat-fr' (french) * WeeChat forum: http://forums.flashtux.org/ * Mailing list: ** subscribe: http://mail.nongnu.org/mailman/listinfo/weechat-support ** send mail to weechat-support@nongnu.org ** archives: http://mail.nongnu.org/archive/html/weechat-support