Zulip Terminal - Zulip 's official terminal client
-
Providing a broadly similar user experience to the Zulip web client, ultimately supporting all of its features -
Enabling all actions to be achieved through the keyboard (see Hot keys ) -
Exploring alternative user interface designs suited to the display and input constraints -
Supporting a wide range of platforms and terminal emulators -
Making best use of available rows/columns to scale from 80x24 upwards (see Small terminal notes )
-
All operations performed by users with extra privileges (owners/admins) -
Accessing and updating all settings -
Using a mouse/pointer to achieve all actions -
An internationalized UI
-
Additional and occasionally different Hot keys to better support keyboard-only navigation; other than directional movement these also include: -
z - zoom in/out, between streams & topics, or all direct messages & specific conversations -
t - toggle view of topics for a stream in left panel ( later adopted for recent topics in web client ) -
# - narrow to messages in which you're mentioned ( @ is already used) -
f - narrow to messages you've starred (are f ollowing)
-
-
Not marking additional messages read when the end of a conversation is visible ( FAQ entry ) -
Emoji and reactions are rendered as text only, for maximum terminal/font compatibility -
Footlinks - footnotes for links (URLs) - make messages readable, while retaining a list of links to cross-reference -
Content previewable in the web client, such as images, are also stored as footlinks
-
Stable releases - These are available on PyPI as the package zulip-term To install, run a command like: pip3 install zulip-term -
Latest (git) versions - The latest development version can be installed from the git repository main branch To install, run a command like: pip3 install git+ https://github.com/zulip/zulip-terminal.git @main
python3 -m venv zt_venv (creates a virtual environment named zt_venv in the current directory) source zt_venv/bin/activate (activates the virtual environment; this assumes a bash-like shell) -
Run one of the install commands above.
-
These are now announced in the # announce>terminal releases topic on the Zulip Community server ( https://chat.zulip.org ), which is visible without an account. If you wish to receive emails when updates are announced, you are welcome to sign up for an account on this server, which will enable you to enable email notifications for the #announce stream ( help article , notifications settings on chat.zulip.org ). -
You can also customize your GitHub Watch setting on the project page to include releases. -
PyPI provides a RSS Release feed , and various other services track this information.
-
zulip-term will prompt you for your server, email and password, and create a zuliprc file for you in that location NOTE: If you use Google, Github or another external authentication to access your Zulip organization then you likely won't have a password set and currently need to create one to use zulip-terminal. -
If your organization is on Zulip cloud, you can visit https://zulip.com/accounts/go?next=/accounts/password/reset to create a new password for your account. -
For self-hosted servers please go to your equivalent of <Zulip server URL>/accounts/password/reset/ to create a new password for your account (eg: https://chat.zulip.org/accounts/password/reset/ ).
-
-
Each time you run zulip-term , you can specify the path to an alternative zuliprc file using the -c or --config-file options, eg. $ zulip-term -c /path/to/zuliprc A .zuliprc file corresponding to your account on a particular Zulip server can be downloaded via Web or Desktop applications connected to that server. In recent versions this can be found in your Personal settings in the Account & privacy section, under API key as 'Show/change your API key'. If this is your only Zulip account, you may want to move and rename this file to the default file location above, or rename it to something more memorable that you can pass to the ---config-file option. This .zuliprc file gives you all the permissions you have as that user. Similar .zuliprc files can be downloaded from the Bots section for any bots you have set up, though with correspondingly limited permissions.
-
an [api] section with information required to connect to your Zulip server -
a [zterm] section with configuration specific to zulip-term
[api] email= example@example.com key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx site= https://example.zulipchat.com [zterm] ## Theme: available themes can be found by running `zulip-term --list-themes`, or in docs/FAQ.md theme=zt_dark ## Autohide: set to 'autohide' to hide the left & right panels except when they're focused autohide=no_autohide ## Exit Confirmation: set to 'disabled' to exit directly with no warning popup first exit_confirmation=enabled ## Footlinks: set to 'disabled' to hide footlinks; ' enabled' will show the first 3 per message ## For more flexibility, comment-out this value, and un-comment maximum-footlinks below footlinks=enabled ## Maximum-footlinks: set to any value 0 or greater, to limit footlinks shown per message # maximum-footlinks=3 ## Notify: set to 'enabled' to display notifications (see elsewhere for configuration notes) notify=disabled ## Color-depth: set to one of 1 (for monochrome), 16, 256, or 24bit color-depth=256
NOTE: Most of these configuration settings may be specified on the command line when
zulip-term is started;
zulip-term -h or
zulip-term --help will give the full list of options.
sudo apt-get install libnotify-bin
echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.bash_profile source ~/.bash_profile
echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.zshenv source ~/.zshenv
sudo apt-get install xclip [Recommended]
sudo apt-get install xsel
-
Prefer text in code blocks , instead of screenshots Zulip Terminal supports downloading images, but there is no guarantee that users will be able to view them. Try Meta + m to see example content formatting, including code blocks -
Prefer silent mentions over regular mentions - or avoid mentions entirely With Zulip's topics, the intended recipient can often already be clear. Experienced members will be present as their time permits - responding to messages when they return - and others may be able to assist before then. (Save regular mentions for those who you do not expect to be present on a regular basis) Try Ctrl + f / b to cycle through autocompletion in message content, after typing @_ to specify a silent mention -
Prefer trimming quote and reply text to only the relevant parts of longer messages - or avoid quoting entirely Zulip's topics often make it clear which message you're replying to. Long messages can be more difficult to read with limited rows and columns of text, but this is worsened if quoting an entire long message with extra content. Try > to quote a selected message, deleting text as normal when composing a message -
Prefer a quick emoji reaction to show agreement instead of simple short messages Reactions take up less space, including in Zulip Terminal, particularly when multiple users wish to respond with the same sentiment. Try + to toggle thumbs-up (+1) on a message, or use : to search for other reactions
$ git clone --config pull.rebase git@github.com :YOUR_USERNAME/zulip-terminal.git
$ git remote add -f upstream https://github.com/zulip/zulip-terminal.git
-
Install pipenv (see the recommended installation notes ; pipenv can be installed in a virtual environment, if you wish)
$ pip3 install --user pipenv
-
Initialize the pipenv virtual environment for zulip-term (using the default python 3; use eg. --python 3.6 to be more specific)
$ pipenv --three
-
Install zulip-term, with the development requirements
$ pipenv install --dev $ pipenv run pip3 install -e '. [dev]'
-
Connect the gitlint commit-message hook
$ pipenv run gitlint install-hook
-
Manually create & activate a virtual environment; any method should work, such as that used in the above simple installation python3 -m venv zt_venv (creates a venv named zt_venv in the current directory) source zt_venv/bin/activate (activates the venv; this assumes a bash-like shell)
-
Install zulip-term, with the development requirements
$ pip3 install -e '. [dev]'
-
Connect the gitlint commit-message hook
$ gitlint install-hook
make (sets up an installed virtual environment in zt_venv in the current directory) source zt_venv/bin/activate (activates the venv; this assumes a bash-like shell) gitlint install-hook (connect the gitlint commit-message hook)
|
|
|
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
make lint and make test run all of each group of tasks make check runs all checks, which is useful before pushing a PR (or an update) tools/check-branch will run make check on each commit in your branch
NOTE: It is highly unlikely that a pull request will be merged, until all linters and tests are passing, including on a per-commit basis.
If you have troubles understanding why the linters or pytest are failing, please do push your code to a branch/PR and we can discuss the problems in the PR or on chat.zulip.org.
tools/lint-hotkeys --fix to regenerate docs/hotkeys.md from config/keys.py tools/lint-docstring --fix to regenerate docs/developer-file-overview.md from file docstrings
-
Minimal : Look at each commit. Does it make different kinds of changes to lots of files? Are you treating the title of a commit as a list of changes? Consider how to break down a large change into a sequence of smaller changes that you can individually easily describe and that can flow after one another. -
Coherent : Each commit should individually pass all linting and existing automated tests, and if you add new behavior, then add or extend the tests to cover it.
-
Minimal commits can always later be squashed (combined) together - splitting commits is more challenging! -
Coherent commits mean nothing should be broken between and after commits -
If a new commit in your branch breaks the linting/tests, it's likely that commit at fault! -
This improves the utility of git bisect in your branch or on main
-
-
These commits are easier to reorder in a branch -
Commits at the start of a branch (or can be moved there), may be merged early to simplify a branch
-
-
Understanding what changes were made and why is easier when reading a git log comprising these commits
-
starting with one or more areas - in lower case, followed by a colon and space -
generally each commit has at least one area of each modified file - without extensions, separated by a / -
generally don't include test files in this list (instead Tests updated or Tests added in the commit text) -
other common areas include types like refactor: , bugfix: and requirements: (see below)
-
-
ending with a concise description starting with a capital and ending with a full-stop (period) -
having a maximum overall length of 72 (fitting the github web interface without abbreviation)
file3/file1/file2: Improve behavior of something. -
a general commit updating files file1.txt , file2.py and file3.md
-
refactor: file1/file2: Extract some common function. -
a pure refactor which doesn't change the functional behavior, involving file1.py and file2.py
-
bugfix: file1: Avoid some noticeable bug. -
a small commit to fix a bug in file1.py
-
tests: file1: Improve test for something. -
only improve tests for file1 , likely in test_file1.py
-
requirements: Upgrade some-dependency from ==9.2 to ==9.3. -
upgrade a dependency from version ==9.2 to version ==9.3, in the central dependencies file ( not some file requirements.*)
-
-
If lots of tests are failing in a very verbose way, you might try the -x option (eg. pytest -x ) to stop tests after the first failure; due to parametrization of tests and test fixtures, many apparent errors/failures can be resolved with just one fix! (try eg. pytest --maxfail 3 for a less-strict version of this) -
To avoid running all the successful tests each time, along with the failures, you can run with --lf (eg. pytest --lf ), short for --last-failed (similar useful options may be --failed-first and --new-first , which may work well with -x ) -
Since pytest 3.10 there is --sw ( --stepwise ), which works through known failures in the same way as --lf and -x can be used, which can be combined with --stepwise-skip to control which test is the current focus -
If you know the names of tests which are failing and/or in a specific location, you might limit tests to a particular location (eg. pytest tests/model ) or use a selected keyword (eg. pytest -k __handle )
print ( f"Just about to do something with { variable } " )
from pudb . remote import set_trace
set_trace ()
$ telnet 127.0.0.1 6899
-
If using pipenv, call pipenv run zulip-term from the cloned/downloaded zulip-terminal directory; -
If using pip (pip3), ensure you have activated the correct virtual environment (venv); depending on how your shell is configured, the name of the venv may appear in the command prompt. Note that not including the -e in the pip3 command will also cause this problem.