doom-emacs/modules/tools/collab

tools/collab

• Description
  • Maintainers
  • Module Flags
  • Plugins
• Prerequisites
  • With +tunnel
    • macOS
    • Linux
    • Windows
• Features
  • Keybindings
• Configuration
• Troubleshooting
  • People outside my LAN can't connect to the collab session I'm hosting
  • I got an error saying something including "crdt.el protocol"

Description

This module adds collaborative editing via the crdt plugin.

Maintainers

• @artenator
• @jming422

Module Flags

• +tunnel Enables TCP forwarding over the Tox protocol so that a collaborative editing session can be established between machines that are behind a NAT.

Plugins

• crdt

Prerequisites

With no flags, this module requires nothing else to work. The +tunnel flag has one dependency:

With +tunnel

Tunneling requires the tuntox program, which is used to establish TCP connections to your collaborators over the Tox peer-to-peer networking protocol.

macOS

tuntox can be installed from Homebrew:

brew install tuntox

Linux

You can download the tuntox binary for most architectures from its Releases page on GitHub, and it can be found in some package manager repositories as well.

Windows

Tuntox is currently not supported on Windows, so Windows users cannot use the +tunnel flag and must choose another networking solution, such as a VPN. For more options, see this Troubleshooting entry.

Features

• Start a collaborative editing session in one of your buffers with M-x crdt-share-buffer and following the prompts.
• If you're using +tunnel, get the sharable URL of your session using M-x crdt-copy-url. If not using +tunnel, then instead of a URL, others can connect using your public IP address and chosen TCP port number (default port is 6530)
• Others can connect to your session using M-x crdt-connect and following the prompts to pass in your tunnel URL or IP address and port

• Once connected, some commands you can use are:

  • crdt-list-buffers to list shared buffers. Use this after crdt-connect to open shared buffers for editing!
  • crdt-share-buffer Start a new collaboration session, or add more buffers to an existing session. Once a session has started, both the host and clients can use this function to share buffers!
  • crdt-goto-user to jump to another collaborator
  • crdt-follow-user / crdt-stop-follow to toggle following another collaborator
  • crdt-visualize-author-mode to add colors to regions of the buffer, visualizing who most recently edited each part of the buffer
  • crdt-stop-session (host) / crdt-disconnect (client) to exit the collab session

Keybindings

When this module is enabled, the `SPC l` leader keymap becomes available, making most of the above functions and more available under that prefix:

Binding	Description
SPC l b	Switch to a shared buffer
SPC l c	Connect to a session
SPC l d	Disconnect from session
SPC l f	Toggle following another user's cursor
SPC l F	Stop following user if any
SPC l g	Goto another user's cursor
SPC l i	List shared buffers
SPC l k	Kick a user (host only)
SPC l l	List sessions
SPC l s	Share current buffer, optionally starting a new session
SPC l S	Stop sharing current buffer
SPC l u	List connected users
SPC l x	Stop a session (host only)
SPC l y	Copy URL of current session
SPC l ]	Goto next user's cursor
SPC l [	Goto previous user's cursor

Configuration

This list is not exhaustive; for the full list of config options, type SPC h V crdt- after loading the module.

Custom variable	Default	Function
crdt-ask-for-name	t	Set to nil to always use crdt-default-name as your name without asking
crdt-default-name	(user-full-name)	Your display name in collaboration sessions
crdt-tuntox-executable	"tuntox"	Path to the tuntox binary
crdt-tuntox-password-in-url	t if +tunnel, else nil	Set to t to put your session password (in plaintext) into the URL made by crdt-copy-url

Troubleshooting

People outside my LAN can't connect to the collab session I'm hosting

Without +tunnel enabled, on most home/work networks you will be unable to have others join you from across the Internet unless you set something up to facilitate the connection between collaborators. You have a lot of options here, but some of the most common are:

• Enable the +tunnel flag to tunnel your traffic using the Tox peer-to-peer networking protocol
• Use a VPN
• Use a non-peer-to-peer tunneling method, such as Teredo. One free software implementation of this method is called Miredo
• Use a TCP reverse proxy server, such as ngrok
• Use SSH port forwarding, if you have access to a server with a public network address

I got an error saying something including "crdt.el protocol"

All collaborators must be using the same version of the crdt package in order to guarantee stability & support for all features. These types of errors should not occur if everyone is up to date, so ensure that all collaborators have upgraded Doom Emacs to the latest version and have not pinned crdt.