{"id":13552430,"url":"https://github.com/dylanaraps/birch","last_synced_at":"2025-04-03T03:31:41.192Z","repository":{"id":55116093,"uuid":"170399831","full_name":"dylanaraps/birch","owner":"dylanaraps","description":"An IRC client written in bash","archived":true,"fork":false,"pushed_at":"2021-01-09T03:20:32.000Z","size":309,"stargazers_count":318,"open_issues_count":4,"forks_count":15,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-03T23:34:51.099Z","etag":null,"topics":["bash","irc","irc-client"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dylanaraps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-12T22:16:24.000Z","updated_at":"2024-10-28T05:05:20.000Z","dependencies_parsed_at":"2022-08-14T12:30:46.278Z","dependency_job_id":null,"html_url":"https://github.com/dylanaraps/birch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanaraps%2Fbirch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanaraps%2Fbirch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanaraps%2Fbirch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylanaraps%2Fbirch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dylanaraps","download_url":"https://codeload.github.com/dylanaraps/birch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246933434,"owners_count":20857048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","irc","irc-client"],"created_at":"2024-08-01T12:02:03.861Z","updated_at":"2025-04-03T03:31:36.119Z","avatar_url":"https://github.com/dylanaraps.png","language":"Shell","funding_links":[],"categories":["Communication and Collaboration Tools","Shell"],"sub_categories":["IRC"],"readme":"m birch\n\nAn IRC client written in bash.\n\n![scrot](https://user-images.githubusercontent.com/6799467/75714877-2793ab80-5cd5-11ea-8aad-92d7f245bdaf.jpg)\n\n## Features\n\n```\n* Full power of readline for input and keybindings. \n\n  This is thanks to bash's `read -e`. Birch will read a readline\n  based configuration file from the environment variable \n  '$BIRCH_INPUTRC' which allows you to customize everything.\n\n* Tab completion of nicks and channels. \n  \n  Bash hardcodes `read -e` tab completion to the file based one. This \n  works fine for channel completion as each channel log is stored in \n  a file anyway. For nick completion, birch will create an empty file \n  for each nick in the channel. Hey, it works.\n\n* Unique (or semi-unique) nick colors.\n\n  All nicks are colored based on their length. The length is mapped\n  to a color between 1 and 6 which is then used as input for \n  '\\033[1;3\u003cmapped_col\u003em'.\n```\n\n## Caveats (or limitations)\n\n```\n* Nick column is fixed and truncated to 10 columns wide.\n  \n  This is something fixable down the line. It merely serves to\n  simplify the alignment of messages into two columns (nick and\n  messages).\n\n* Lines are word-wrapped to a fixed 60 columns.\n\n  This is also fixable down the line though a lot more painful\n  than the nick column issue. POSIX fold is used to achieve the\n  word wrapping but doesn't take into account non-printable\n  characters and unicode.\n\n  What this means is that wrapping will always be a little _off_\n  as escape sequences, IRC formatting and unicode will throw\n  out all attempts at calculating the \"visible\" line length.\n\n  It's an interesting problem to solve. I've made a myriad of\n  attempts at writing a suitable function in bash though they're\n  all too slow (as expected!).\n\n* No automatic server reconnect.\n\n  This should be fairly easy to fix though I need to figure out\n  the best way of doing so.\n\n* No SSL (sadly).\n\n  The network connection is through bash's builtin /dev/tcp\n  feature which doesn't allow for SSL.\n```\n\n\n## Interesting facts\n\n```\n* Connection to the IRC server happens without external\n  utilities.\n\n  Bash support network connections via two virtual device\n  directories it \"creates\" in '/dev/'. \n\n  '/dev/tcp/host/port' and '/dev/udp/host/port'.\n\n  I don't exactly know _why_ these were implemented as\n  it's a crazy feature for a shell to have. I haven't seen\n  them widely used either.\n\n* The input loop and listener loop can't communicate.\n\n  Birch utilizes two loops to work. One for the input and \n  an additional loop to listen to incoming IRC messages.\n\n  When something is run asynchronously in bash with '\u0026', it\n  runs in a subshell (a second bash process).\n\n  What this means is that the async code can't communicate\n  with the blocking code. Any variables set in the input loop\n  once both loops are running won't be visible in the async\n  listener loop to give an example.\n\n  To work around this birch utilizes files for IPC between the\n  two. The current channel is communicated by maintaining a \n  symlink and checking its target where needed.\n\n  Example: .c -\u003e '#current_channel'\n\n* This was HARD.\n\n  Trying to make the input prompt and async listener (which\n  spits out messages to the terminal) play nice took a lot\n  of work.\n\n  As birch implements a TUI _manually_ we're dealing with bare\n  escape sequences to tie everything together.\n\n  When a message needs to be printed, the cursor must move from\n  the input prompt to the output area, print the message and\n  finally return back to the input prompt.\n\n  All of this must happen just right to ensure that this series\n  of cursor movements doesn't end up mangling the display of \n  the interface.\n\n  Birch has gone through a lot of rewrites to get this perfect.\n  Fun fact: The older revisions read input char by char and\n  implemented a lot of readline by hand.\n```\n\n\n## Usage\n\n```sh\nbirch \u003cargs\u003e\n\n-s \u003chost\u003e\n-c \u003cchannel\u003e\n-u \u003cnick\u003e\n-p \u003cserver_password\u003e\n-U \u003cserver_username\u003e\n-P \u003cport\u003e\n-x \u003ccmd\u003e\n\n-h (help)\n-v (version)\n```\n\n## Dependencies\n\n- `bash 4+`\n- POSIX compatible `fold`, `rm`\n\n\n## Keybindings\n\n```\nCtrl+n - Next buffer.\nCtrl+p - Previous buffer.\nTab    - Completion of nicks and channels.\n\nFurther, all readline keybindings are available for use. See the\nreadline or bash manpages for a list of these. \n\nKeybindings to birch may also be set via a .inputrc file. Which\ncan be configured by setting `$BIRCH_INPUTRC`.\n\n(BIRCH_INPUTRC=/path/to/birch-inputrc birch)\n```\n\n\n## Commands\n\n```\nChannels:\n\n/join \u003cchannel\u003e       - Join a channel.\n/part \u003cchannel\u003e       - Leave a channel.\n/quit                 - Quit out of birch.\n\nMessages: \n\n/msg \u003cnick\u003e \u003cmessage\u003e - Message a user.\n/me  \u003cmessage\u003e        - Send an action.\n\nNavigation:\n\n/next                 - Next buffer.\n/prev                 - Previous buffer.\n/\u003cnum\u003e                - Buffer by number (0 indexed).\n\nOther:\n\n/nick \u003cnick\u003e          - Change nickname.\n/names                - Display all nicks in channel.\n/topic                - Display channel topic.\n/away \u003cmessage\u003e       - Set afk message.\n/raw \u003cargs\u003e           - Send a raw IRC message.\n```\n\n\n## Customization\n\n```\n(These are environment variables.)\n\n# Set the formatting of the tab line's selected item.\n# This defaults to reverse video.\nBIRCH_STATUS='\\e[7m'\n\n# The path to a readline based .inputrc file to change\n# birch's input settings. \n#\n# See http://man7.org/linux/man-pages/man3/readline.3.html\nBIRCH_INPUTRC=/path/to/file\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylanaraps%2Fbirch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdylanaraps%2Fbirch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylanaraps%2Fbirch/lists"}