| Name | jwodder-ps1 JSON |
| Version |
0.7.2
JSON |
| download |
| home_page | None |
| Summary | Yet another bash/zsh custom prompt script |
| upload_time | 2024-07-11 10:52:32 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
bash
git
prompt
ps1
zsh
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
|repostatus| |ci-status| |coverage| |pyversions| |license|
.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg
:target: https://www.repostatus.org/#active
:alt: Project Status: Active — The project has reached a stable, usable
state and is being actively developed.
.. |ci-status| image:: https://github.com/jwodder/ps1.py/actions/workflows/test.yml/badge.svg
:target: https://github.com/jwodder/ps1.py/actions/workflows/test.yml
:alt: CI Status
.. |coverage| image:: https://codecov.io/gh/jwodder/ps1.py/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jwodder/ps1.py
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/jwodder-ps1.svg
:target: https://pypi.org/project/jwodder-ps1/
.. |license| image:: https://img.shields.io/github/license/jwodder/ps1.py.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT License
`GitHub <https://github.com/jwodder/ps1.py>`_
| `PyPI <https://pypi.org/project/jwodder-ps1/>`_
| `Issues <https://github.com/jwodder/ps1.py/issues>`_
``jwodder-ps1`` is yet another program for Git-aware customization of the
command prompt in Bash and zsh. Unlike all the others, I wrote this one, so
it's better.
.. image:: https://github.com/jwodder/ps1.py/raw/master/screenshot.png
Features:
- Lets you know if you have mail in ``$MAIL``
- Shows chroot, `virtualenv <https://virtualenv.pypa.io>`_, and `Conda
<https://conda.io>`_ environment prompt prefixes
- Automatically truncates the current directory path if it gets too long
- Shows the status of the current Git repository (see below)
- Supports both Bash and zsh
- Can optionally output just the Git status, in case you want to combine it
with your own prompt string
Installation & Setup
====================
``jwodder-ps1`` requires Python 3.9 or higher. You'll also need a Bash or zsh
shell to set the program up in, and you'll need ``git`` v1.7.10+ installed in
order to get status information about Git repositories.
Install the ``jwodder-ps1`` command by using `pip <https://pip.pypa.io>`_ or
similar (using `pipx <https://pipx.pypa.io>`_ is recommended) to install the
package of the same name from PyPI.
If you use Bash, configure it to use ``jwodder-ps1`` for the prompt by adding
the following line to the end of your ``~/.bashrc``:
.. code:: shell
PROMPT_COMMAND="$PROMPT_COMMAND"'; PS1="$(jwodder-ps1 "${PS1_GIT:-}")"'
If you use zsh instead, add the following to the end of your ``~/.zshrc``:
.. code:: shell
precmd_jwodder_ps1() { PS1="$(jwodder-ps1 --zsh "${PS1_GIT:-}")" }
precmd_functions+=( precmd_jwodder_ps1 )
If you want to use just the Git status portion of the script's output and
combine it with your own prompt string, replace the ``PS1`` assignment with
your desired prompt, with ``$(jwodder-ps1 --git-only "${PS1_GIT:-}")`` inserted
where you want the Git status string.
Depending on how ``jwodder-ps1`` was installed and what the value of your
``PATH`` is, you may have to use the full path to the ``jwodder-ps1``
executable instead.
Once ``jwodder-ps1`` is configured, open a new shell and enjoy!
If the Git integration causes you trouble (either because something breaks or
just because it's taking too long to run), it can be temporarily disabled by
running ``PS1_GIT=off`` on the command line.
Usage
=====
::
jwodder-ps1 [<options>] [<git flag>]
The ``jwodder-ps1`` command outputs a single line containing a stylized prompt
string for the current directory. By default, the stylization is in a format
usable in Bash's ``PS1`` variable, though the ``--ansi`` and ``--zsh`` option
can be supplied to change the format.
``jwodder-ps1`` takes a single optional argument. If this argument is "off",
then the Git integration is disabled. If it is any other value or not
specified, the Git integration is enabled.
Options
-------
--ansi Format output for direct display
--bash Format output for use in Bash's ``PS1`` (default)
-G, --git-only Only output the Git status string (including leading
separator); output an empty line if not in a Git repository or
if "off" is given on the command line
--git-timeout SECONDS
If running ``git status`` takes longer than the given number of
seconds (default: 3), disable the Git integration
--no-hostname Do not include the local hostname in the prompt string
-T THEME, --theme THEME
Select the theme to use for coloring prompt elements. The
available themes are ``dark`` (the default, for use with light
text on dark backgrounds) and ``light`` (for use with dark text
on light backgrounds).
--zsh Format output for use in zsh's ``PS1``
-V, --version Display version information and exit
-h, --help Display usage information and exit
Git Status Symbols
==================
When inside a Git repository, a number of symbols showing the current ``HEAD``
and its status are added near the end of the prompt. Except for the ``@``
separator and the ``HEAD`` itself, individual symbols are omitted when not
relevant. From left to right, the symbols are:
- ``@`` — separator
- ``+`` (bold light yellow) — Indicates there are stashed changes
- The name of the ``HEAD`` (light green): the name of the current branch (if
any), or the name of the currently checked-out tag (if any), or the short
form of the current commit hash. This is light blue when the repository is
in a detached ``HEAD`` state.
This string is truncated if it gets too long.
- ``+n`` (green) — how many commits ``HEAD`` is ahead of upstream
- ``-n`` (red) — how many commits ``HEAD`` is behind upstream
- ``*`` — Indicates whether there are any staged or unstaged changes in the
working tree:
- Green: There are staged changes
- Red: There are unstaged changes
- Bold light yellow: There are both staged and unstaged changes
- ``+`` (bold red) — Indicates there are untracked files in the working tree
- ``[STATE]`` (magenta) — Shows what activity Git is currently in the middle
of, if any:
- ``[BSECT]`` — bisecting
- ``[CHYPK]`` — cherry-picking
- ``[MERGE]`` — merging
- ``[REBAS]`` — rebasing
- ``[REVRT]`` — reverting
- ``!`` (bold red) — Indicates there are paths with merge conflicts
Raw data
{
"_id": null,
"home_page": null,
"name": "jwodder-ps1",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "bash, git, prompt, ps1, zsh",
"author": null,
"author_email": "John Thorvald Wodder II <ps1@varonathe.org>",
"download_url": "https://files.pythonhosted.org/packages/00/cf/a6261801878bec2edf9a649924149f1912fcc8f048adcd3693e9b91bc4da/jwodder_ps1-0.7.2.tar.gz",
"platform": null,
"description": "|repostatus| |ci-status| |coverage| |pyversions| |license|\n\n.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg\n :target: https://www.repostatus.org/#active\n :alt: Project Status: Active \u2014 The project has reached a stable, usable\n state and is being actively developed.\n\n.. |ci-status| image:: https://github.com/jwodder/ps1.py/actions/workflows/test.yml/badge.svg\n :target: https://github.com/jwodder/ps1.py/actions/workflows/test.yml\n :alt: CI Status\n\n.. |coverage| image:: https://codecov.io/gh/jwodder/ps1.py/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/jwodder/ps1.py\n\n.. |pyversions| image:: https://img.shields.io/pypi/pyversions/jwodder-ps1.svg\n :target: https://pypi.org/project/jwodder-ps1/\n\n.. |license| image:: https://img.shields.io/github/license/jwodder/ps1.py.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT License\n\n`GitHub <https://github.com/jwodder/ps1.py>`_\n| `PyPI <https://pypi.org/project/jwodder-ps1/>`_\n| `Issues <https://github.com/jwodder/ps1.py/issues>`_\n\n``jwodder-ps1`` is yet another program for Git-aware customization of the\ncommand prompt in Bash and zsh. Unlike all the others, I wrote this one, so\nit's better.\n\n.. image:: https://github.com/jwodder/ps1.py/raw/master/screenshot.png\n\nFeatures:\n\n- Lets you know if you have mail in ``$MAIL``\n- Shows chroot, `virtualenv <https://virtualenv.pypa.io>`_, and `Conda\n <https://conda.io>`_ environment prompt prefixes\n- Automatically truncates the current directory path if it gets too long\n- Shows the status of the current Git repository (see below)\n- Supports both Bash and zsh\n- Can optionally output just the Git status, in case you want to combine it\n with your own prompt string\n\n\nInstallation & Setup\n====================\n\n``jwodder-ps1`` requires Python 3.9 or higher. You'll also need a Bash or zsh\nshell to set the program up in, and you'll need ``git`` v1.7.10+ installed in\norder to get status information about Git repositories.\n\nInstall the ``jwodder-ps1`` command by using `pip <https://pip.pypa.io>`_ or\nsimilar (using `pipx <https://pipx.pypa.io>`_ is recommended) to install the\npackage of the same name from PyPI.\n\nIf you use Bash, configure it to use ``jwodder-ps1`` for the prompt by adding\nthe following line to the end of your ``~/.bashrc``:\n\n.. code:: shell\n\n PROMPT_COMMAND=\"$PROMPT_COMMAND\"'; PS1=\"$(jwodder-ps1 \"${PS1_GIT:-}\")\"'\n\nIf you use zsh instead, add the following to the end of your ``~/.zshrc``:\n\n.. code:: shell\n\n precmd_jwodder_ps1() { PS1=\"$(jwodder-ps1 --zsh \"${PS1_GIT:-}\")\" }\n precmd_functions+=( precmd_jwodder_ps1 )\n\nIf you want to use just the Git status portion of the script's output and\ncombine it with your own prompt string, replace the ``PS1`` assignment with\nyour desired prompt, with ``$(jwodder-ps1 --git-only \"${PS1_GIT:-}\")`` inserted\nwhere you want the Git status string.\n\nDepending on how ``jwodder-ps1`` was installed and what the value of your\n``PATH`` is, you may have to use the full path to the ``jwodder-ps1``\nexecutable instead.\n\nOnce ``jwodder-ps1`` is configured, open a new shell and enjoy!\n\nIf the Git integration causes you trouble (either because something breaks or\njust because it's taking too long to run), it can be temporarily disabled by\nrunning ``PS1_GIT=off`` on the command line.\n\n\nUsage\n=====\n\n::\n\n jwodder-ps1 [<options>] [<git flag>]\n\nThe ``jwodder-ps1`` command outputs a single line containing a stylized prompt\nstring for the current directory. By default, the stylization is in a format\nusable in Bash's ``PS1`` variable, though the ``--ansi`` and ``--zsh`` option\ncan be supplied to change the format.\n\n``jwodder-ps1`` takes a single optional argument. If this argument is \"off\",\nthen the Git integration is disabled. If it is any other value or not\nspecified, the Git integration is enabled.\n\nOptions\n-------\n\n--ansi Format output for direct display\n\n--bash Format output for use in Bash's ``PS1`` (default)\n\n-G, --git-only Only output the Git status string (including leading\n separator); output an empty line if not in a Git repository or\n if \"off\" is given on the command line\n\n--git-timeout SECONDS\n If running ``git status`` takes longer than the given number of\n seconds (default: 3), disable the Git integration\n\n--no-hostname Do not include the local hostname in the prompt string\n\n-T THEME, --theme THEME\n Select the theme to use for coloring prompt elements. The\n available themes are ``dark`` (the default, for use with light\n text on dark backgrounds) and ``light`` (for use with dark text\n on light backgrounds).\n\n--zsh Format output for use in zsh's ``PS1``\n\n-V, --version Display version information and exit\n\n-h, --help Display usage information and exit\n\n\nGit Status Symbols\n==================\n\nWhen inside a Git repository, a number of symbols showing the current ``HEAD``\nand its status are added near the end of the prompt. Except for the ``@``\nseparator and the ``HEAD`` itself, individual symbols are omitted when not\nrelevant. From left to right, the symbols are:\n\n- ``@`` \u2014 separator\n- ``+`` (bold light yellow) \u2014 Indicates there are stashed changes\n- The name of the ``HEAD`` (light green): the name of the current branch (if\n any), or the name of the currently checked-out tag (if any), or the short\n form of the current commit hash. This is light blue when the repository is\n in a detached ``HEAD`` state.\n\n This string is truncated if it gets too long.\n\n- ``+n`` (green) \u2014 how many commits ``HEAD`` is ahead of upstream\n- ``-n`` (red) \u2014 how many commits ``HEAD`` is behind upstream\n- ``*`` \u2014 Indicates whether there are any staged or unstaged changes in the\n working tree:\n\n - Green: There are staged changes\n - Red: There are unstaged changes\n - Bold light yellow: There are both staged and unstaged changes\n\n- ``+`` (bold red) \u2014 Indicates there are untracked files in the working tree\n- ``[STATE]`` (magenta) \u2014 Shows what activity Git is currently in the middle\n of, if any:\n\n - ``[BSECT]`` \u2014 bisecting\n - ``[CHYPK]`` \u2014 cherry-picking\n - ``[MERGE]`` \u2014 merging\n - ``[REBAS]`` \u2014 rebasing\n - ``[REVRT]`` \u2014 reverting\n\n- ``!`` (bold red) \u2014 Indicates there are paths with merge conflicts\n",
"bugtrack_url": null,
"license": null,
"summary": "Yet another bash/zsh custom prompt script",
"version": "0.7.2",
"project_urls": {
"Bug Tracker": "https://github.com/jwodder/ps1.py/issues",
"Source Code": "https://github.com/jwodder/ps1.py"
},
"split_keywords": [
"bash",
" git",
" prompt",
" ps1",
" zsh"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d07b49eb5d97087f31c0e02b11d824996bd75c878b045e9ab79957c329fea9f9",
"md5": "3a6a567a237077805ae76c04fce86efb",
"sha256": "16131912afb63e2c3154f4cd0ace46e6ce3a2b3154ad92df02029c577be39c0c"
},
"downloads": -1,
"filename": "jwodder_ps1-0.7.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a6a567a237077805ae76c04fce86efb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13696,
"upload_time": "2024-07-11T10:52:30",
"upload_time_iso_8601": "2024-07-11T10:52:30.974295Z",
"url": "https://files.pythonhosted.org/packages/d0/7b/49eb5d97087f31c0e02b11d824996bd75c878b045e9ab79957c329fea9f9/jwodder_ps1-0.7.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00cfa6261801878bec2edf9a649924149f1912fcc8f048adcd3693e9b91bc4da",
"md5": "6f35e6fcd8e8fdfb3e5e7f2c726ad8c8",
"sha256": "3f95ccb40f08eb1a291668b0bd14b37a88ae0ebb4a481007f49ee1bbec142659"
},
"downloads": -1,
"filename": "jwodder_ps1-0.7.2.tar.gz",
"has_sig": false,
"md5_digest": "6f35e6fcd8e8fdfb3e5e7f2c726ad8c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 14454,
"upload_time": "2024-07-11T10:52:32",
"upload_time_iso_8601": "2024-07-11T10:52:32.058840Z",
"url": "https://files.pythonhosted.org/packages/00/cf/a6261801878bec2edf9a649924149f1912fcc8f048adcd3693e9b91bc4da/jwodder_ps1-0.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-11 10:52:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jwodder",
"github_project": "ps1.py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jwodder-ps1"
}
