mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-26 12:53:13 +00:00
docs: update the VCS prompt function documentation
Edited for clarity and formatting. [ci skip]
This commit is contained in:
David Adam
parent
c50eb7c85f
commit
87518a524f
4 changed files with 111 additions and 118 deletions
|
|
@ -6,26 +6,32 @@ fish_git_prompt - output git information for use in a prompt
|
|||
Description
|
||||
-----------
|
||||
|
||||
The fish_git_prompt function can be used to display information about the current git repository, if any.
|
||||
The ``fish_git_prompt`` function displays information about the current git repository, if any.
|
||||
|
||||
For obvious reasons, it requires having git installed.
|
||||
`Git <https://git-scm.com>`_ must be installed.
|
||||
|
||||
There are numerous configuration options, either as fish variables or git config variables. If a git config variable is supported, it will be used if set, and the fish variable will only be used if it isn't.
|
||||
There are numerous customization options, which can be controlled with git options or fish variables. git options, where available, take precedence over the fish variable with the same function. git options can be set on a per-repository or global basis. git options can be set with the `git config` command, while fish variables can be set as usual with the :ref:`set <cmd-set>` command.
|
||||
|
||||
- ``$__fish_git_prompt_show_informative_status`` or the git config option "bash.showInformativeStatus" can be set to enable the "informative" display, which will show a large amount of information - the number of untracked files, dirty files, unpushed/unpulled commits, etc... In large repositories, this can take a lot of time, so it is recommended to disable it there, via ``git config bash.showInformativeStatus false``.
|
||||
- ``$__fish_git_prompt_show_informative_status`` or the git option ``bash.showInformativeStatus`` can be set to enable the "informative" display, which will show a large amount of information - the number of untracked files, dirty files, unpushed/unpulled commits, and more. In large repositories, this can take a lot of time, so it you may wish to disable it in these repositories with ``git config --local bash.showInformativeStatus false``.
|
||||
|
||||
- ``$__fish_git_prompt_showdirtystate`` or the git config option "bash.showDirtyState" can be set to show if the repository is "dirty", i.e. has uncommitted changes.
|
||||
- ``$__fish_git_prompt_showdirtystate`` or the git option ``bash.showDirtyState`` can be set to show if the repository is "dirty", i.e. has uncommitted changes.
|
||||
|
||||
- ``$__fish_git_prompt_showuntrackedfiles`` or the git config option "bash.showUntrackedFiles" can be set to show if the repository has untracked files (that aren't ignored).
|
||||
- ``$__fish_git_prompt_showuntrackedfiles`` or the git option ``bash.showUntrackedFiles`` can be set to show if the repository has untracked files (that aren't ignored).
|
||||
|
||||
- ``$__fish_git_prompt_showupstream`` can be set to a number of values to determine how changes between HEAD and upstream are shown:
|
||||
|
||||
verbose show number of commits ahead/behind (+/-) upstream
|
||||
name if verbose, then also show the upstream abbrev name
|
||||
informative similar to verbose, but shows nothing when equal - this is the default if show_informative_status is set.
|
||||
git always compare HEAD to @{upstream}
|
||||
svn always compare HEAD to your SVN upstream
|
||||
none disables (useful with show_informative_status)
|
||||
``verbose``
|
||||
show number of commits ahead/behind (+/-) upstream
|
||||
``name``
|
||||
if verbose, then also show the upstream abbrev name
|
||||
``informative``
|
||||
similar to verbose, but shows nothing when equal - this is the default if informative status is enabled.
|
||||
``git``
|
||||
always compare HEAD to @{upstream}
|
||||
``svn``
|
||||
always compare HEAD to your SVN upstream
|
||||
``none``
|
||||
disables (useful with informative status)
|
||||
|
||||
- ``$__fish_git_prompt_showstashstate`` can be set to display the state of the stash.
|
||||
|
||||
|
|
@ -33,14 +39,18 @@ There are numerous configuration options, either as fish variables or git config
|
|||
|
||||
- ``$__fish_git_prompt_describe_style`` can be set to a number of styles that describe the current HEAD:
|
||||
|
||||
contains
|
||||
branch
|
||||
describe
|
||||
default
|
||||
``contains``
|
||||
relative to newer annotated tag, such as ``(v1.6.3.2~35)``
|
||||
``branch``
|
||||
relative to newer tag or branch, such as ``(master~4)``
|
||||
``describe``
|
||||
relative to older annotated tag, such as ``(v1.6.3.1-13-gdd42c2f)``
|
||||
``default``
|
||||
exactly matching tag
|
||||
|
||||
- ``$__fish_git_prompt_showcolorhints`` can be set to enable coloring for certain things.
|
||||
- ``$__fish_git_prompt_showcolorhints`` can be set to enable coloring for the branch name and status symbols.
|
||||
|
||||
A number of variables set characters and color used to indicate things. Many of these have a different default if used with informative status enabled. The normal default is given first, then the informative default if it is different. If no default for the colors is given, they default to ``$__fish_git_prompt_color``.
|
||||
A number of variables set characters and color used as indicators. Many of these have a different default if used with informative status enabled. The usual default is given first, then the informative default (if it is different). If no default for the colors is given, they default to ``$__fish_git_prompt_color``.
|
||||
|
||||
- ``$__fish_git_prompt_char_stateseparator`` (' ', `|`)
|
||||
- ``$__fish_git_prompt_color`` ('')
|
||||
|
|
@ -49,12 +59,12 @@ A number of variables set characters and color used to indicate things. Many of
|
|||
- ``$__fish_git_prompt_color_bare``
|
||||
- ``$__fish_git_prompt_color_merging``
|
||||
|
||||
Some variables are only used in some modes, like when informative status is enabled (by setting ``$__fish_git_prompt_show_informative_status``):
|
||||
Some variables are only used in some modes, like when informative status is enabled:
|
||||
|
||||
- ``$__fish_git_prompt_char_cleanstate`` (✔)
|
||||
- ``$__fish_git_prompt_color_cleanstate``
|
||||
|
||||
Variables used with showdirtystate:
|
||||
Variables used with ``showdirtystate``:
|
||||
|
||||
- ``$__fish_git_prompt_char_dirtystate`` (`*`, ✚)
|
||||
- ``$__fish_git_prompt_char_invalidstate`` (#, ✖)
|
||||
|
|
@ -63,17 +73,17 @@ Variables used with showdirtystate:
|
|||
- ``$__fish_git_prompt_color_invalidstate``
|
||||
- ``$__fish_git_prompt_color_stagedstate`` (green with showcolorhints, color_flags otherwise)
|
||||
|
||||
Variables used with showstashstate:
|
||||
Variables used with ``showstashstate``:
|
||||
|
||||
- ``$__fish_git_prompt_char_stashstate`` (``$``, ⚑)
|
||||
- ``$__fish_git_prompt_color_stashstate`` (same as color_flags)
|
||||
|
||||
Variables used with showuntrackedfiles:
|
||||
Variables used with ``showuntrackedfiles``:
|
||||
|
||||
- ``$__fish_git_prompt_char_untrackedfiles`` (%, …)
|
||||
- ``$__fish_git_prompt_color_untrackedfiles`` (same as color_flags)
|
||||
|
||||
Variables used with showupstream (also implied by informative status):
|
||||
Variables used with ``showupstream`` (also implied by informative status):
|
||||
|
||||
- ``$__fish_git_prompt_char_upstream_ahead`` (>, ↑)
|
||||
- ``$__fish_git_prompt_char_upstream_behind`` (<, ↓)
|
||||
|
|
@ -82,15 +92,15 @@ Variables used with showupstream (also implied by informative status):
|
|||
- ``$__fish_git_prompt_char_upstream_prefix`` ('')
|
||||
- ``$__fish_git_prompt_color_upstream``
|
||||
|
||||
Colors used with showcolorhints:
|
||||
Colors used with ``showcolorhints``:
|
||||
|
||||
- ``$__fish_git_prompt_color_branch`` (green)
|
||||
- ``$__fish_git_prompt_color_branch_detached`` (red)
|
||||
- ``$__fish_git_prompt_color_flags`` (--bold blue)
|
||||
|
||||
Note that all colors can also have a corresponding "_done" color. E.g. ``$__fish_git_prompt_color_upstream_done``, used right _after_ the upstream.
|
||||
Note that all colors can also have a corresponding ``_done`` color. For example, the contents of ``$__fish_git_prompt_color_upstream_done`` is printed right _after_ the upstream.
|
||||
|
||||
See also fish_vcs_prompt, which will call all supported vcs-prompt functions, including git, hg and svn.
|
||||
See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
|
||||
|
||||
Example
|
||||
--------
|
||||
|
|
|
|||
|
|
@ -1,40 +1,40 @@
|
|||
.. _cmd-fish_hg_prompt:
|
||||
|
||||
fish_hg_prompt - output mercurial information for use in a prompt
|
||||
fish_hg_prompt - output Mercurial information for use in a prompt
|
||||
=================================================================
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
The fish_hg_prompt function can be used to display information about the current mercurial repository, if any.
|
||||
The fish_hg_prompt function displays information about the current Mercurial repository, if any.
|
||||
|
||||
For obvious reasons, it requires having hg installed.
|
||||
`Mercurial <https://www.mercurial-scm.org/>`_ (``hg``) must be installed.
|
||||
|
||||
There are numerous configuration options:
|
||||
There are numerous customization options, which can be controlled with fish variables.
|
||||
|
||||
- $fish_color_hg_clean, $fish_color_hg_modified and $fish_color_hg_dirty: The color to use when the repo has the respective status
|
||||
- ``$fish_color_hg_clean``, ``$fish_color_hg_modified`` and ``$fish_color_hg_dirty`` are colors used when the repository has the respective status.
|
||||
|
||||
Some colors for status symbols:
|
||||
|
||||
- $fish_color_hg_added
|
||||
- $fish_color_hg_renamed
|
||||
- $fish_color_hg_copied
|
||||
- $fish_color_hg_deleted
|
||||
- $fish_color_hg_untracked
|
||||
- $fish_color_hg_unmerged
|
||||
- ``$fish_color_hg_added``
|
||||
- ``$fish_color_hg_renamed``
|
||||
- ``$fish_color_hg_copied``
|
||||
- ``$fish_color_hg_deleted``
|
||||
- ``$fish_color_hg_untracked``
|
||||
- ``$fish_color_hg_unmerged``
|
||||
|
||||
And the status symbols themselves:
|
||||
The status symbols themselves:
|
||||
|
||||
- $fish_prompt_hg_status_added, default '✚'
|
||||
- $fish_prompt_hg_status_modified, default '*'
|
||||
- $fish_prompt_hg_status_copied, default '⇒'
|
||||
- $fish_prompt_hg_status_deleted, default '✖'
|
||||
- $fish_prompt_hg_status_untracked, default '?'
|
||||
- $fish_prompt_hg_status_unmerged, default '!'
|
||||
- ``$fish_prompt_hg_status_added``, default '✚'
|
||||
- ``$fish_prompt_hg_status_modified``, default '*'
|
||||
- ``$fish_prompt_hg_status_copied``, default '⇒'
|
||||
- ``$fish_prompt_hg_status_deleted``, default '✖'
|
||||
- ``$fish_prompt_hg_status_untracked``, default '?'
|
||||
- ``$fish_prompt_hg_status_unmerged``, default '!'
|
||||
|
||||
And $fish_prompt_hg_status_order, which can be used to change the order the status symbols appear in. It defaults to ``added modified copied deleted untracked unmerged``.
|
||||
Finally, ``$fish_prompt_hg_status_order``, which can be used to change the order the status symbols appear in. It defaults to ``added modified copied deleted untracked unmerged``.
|
||||
|
||||
See also fish_vcs_prompt, which will call all supported vcs-prompt functions, including git, hg and svn.
|
||||
See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -1,77 +1,60 @@
|
|||
.. _cmd-fish_svn_prompt:
|
||||
|
||||
fish_svn_prompt - output svn information for use in a prompt
|
||||
============================================================
|
||||
fish_svn_prompt - output Subversion information for use in a prompt
|
||||
===================================================================
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
The fish_svn_prompt function displays information about the current Subversion repository, if any.
|
||||
|
||||
The fish_svn_prompt function can be used to display information about the current svn repository, if any.
|
||||
`Subversion <https://subversion.apache.org/>`_ (``svn``) must be installed.
|
||||
|
||||
For obvious reasons, it requires having svn installed.
|
||||
There are numerous customization options, which can be controlled with fish variables.
|
||||
|
||||
There are numerous configuration options:
|
||||
- ``$__fish_svn_prompt_color_revision``
|
||||
the colour of the revision number to display in the prompt
|
||||
- ``$__fish_svn_prompt_char_separator``
|
||||
the separator between status characters
|
||||
|
||||
A number of variables control the symbol ("display") and color ("color") for the different status indicators:
|
||||
|
||||
- $__fish_svn_prompt_color_revision, the colour of the revision number to display in the prompt
|
||||
- $__fish_svn_prompt_char_separator, the separator between status characters
|
||||
- ``$__fish_svn_prompt_char_added_display``
|
||||
- ``$__fish_svn_prompt_char_added_color``
|
||||
- ``$__fish_svn_prompt_char_conflicted_display``
|
||||
- ``$__fish_svn_prompt_char_conflicted_color``
|
||||
- ``$__fish_svn_prompt_char_deleted_display``
|
||||
- ``$__fish_svn_prompt_char_deleted_color``
|
||||
- ``$__fish_svn_prompt_char_ignored_display``
|
||||
- ``$__fish_svn_prompt_char_ignored_color``
|
||||
- ``$__fish_svn_prompt_char_modified_display``
|
||||
- ``$__fish_svn_prompt_char_modified_color``
|
||||
- ``$__fish_svn_prompt_char_replaced_display``
|
||||
- ``$__fish_svn_prompt_char_replaced_color``
|
||||
- ``$__fish_svn_prompt_char_unversioned_external_display``
|
||||
- ``$__fish_svn_prompt_char_unversioned_external_color``
|
||||
- ``$__fish_svn_prompt_char_unversioned_display``
|
||||
- ``$__fish_svn_prompt_char_unversioned_color``
|
||||
- ``$__fish_svn_prompt_char_missing_display``
|
||||
- ``$__fish_svn_prompt_char_missing_color``
|
||||
- ``$__fish_svn_prompt_char_versioned_obstructed_display``
|
||||
- ``$__fish_svn_prompt_char_versioned_obstructed_color``
|
||||
- ``$__fish_svn_prompt_char_locked_display``
|
||||
- ``$__fish_svn_prompt_char_locked_color``
|
||||
- ``$__fish_svn_prompt_char_scheduled_display``
|
||||
- ``$__fish_svn_prompt_char_scheduled_color``
|
||||
- ``$__fish_svn_prompt_char_switched_display``
|
||||
- ``$__fish_svn_prompt_char_switched_color``
|
||||
- ``$__fish_svn_prompt_char_token_present_display``
|
||||
- ``$__fish_svn_prompt_char_token_present_color``
|
||||
- ``$__fish_svn_prompt_char_token_other_display``
|
||||
- ``$__fish_svn_prompt_char_token_other_color``
|
||||
- ``$__fish_svn_prompt_char_token_stolen_display``
|
||||
- ``$__fish_svn_prompt_char_token_stolen_color``
|
||||
- ``$__fish_svn_prompt_char_token_broken_display``
|
||||
- ``$__fish_svn_prompt_char_token_broken_color``
|
||||
|
||||
And
|
||||
- $__fish_svn_prompt_char_added_display
|
||||
- $__fish_svn_prompt_char_added_color
|
||||
|
||||
- $__fish_svn_prompt_char_conflicted_display
|
||||
- $__fish_svn_prompt_char_conflicted_color
|
||||
|
||||
- $__fish_svn_prompt_char_deleted_display
|
||||
- $__fish_svn_prompt_char_deleted_color
|
||||
|
||||
- $__fish_svn_prompt_char_ignored_display
|
||||
- $__fish_svn_prompt_char_ignored_color
|
||||
|
||||
- $__fish_svn_prompt_char_modified_display
|
||||
- $__fish_svn_prompt_char_modified_color
|
||||
|
||||
- $__fish_svn_prompt_char_replaced_display
|
||||
- $__fish_svn_prompt_char_replaced_color
|
||||
|
||||
- $__fish_svn_prompt_char_unversioned_external_display
|
||||
- $__fish_svn_prompt_char_unversioned_external_color
|
||||
|
||||
- $__fish_svn_prompt_char_unversioned_display
|
||||
- $__fish_svn_prompt_char_unversioned_color
|
||||
|
||||
- $__fish_svn_prompt_char_missing_display
|
||||
- $__fish_svn_prompt_char_missing_color
|
||||
|
||||
- $__fish_svn_prompt_char_versioned_obstructed_display
|
||||
- $__fish_svn_prompt_char_versioned_obstructed_color
|
||||
|
||||
- $__fish_svn_prompt_char_locked_display
|
||||
- $__fish_svn_prompt_char_locked_color
|
||||
|
||||
- $__fish_svn_prompt_char_scheduled_display
|
||||
- $__fish_svn_prompt_char_scheduled_color
|
||||
|
||||
- $__fish_svn_prompt_char_switched_display
|
||||
- $__fish_svn_prompt_char_switched_color
|
||||
|
||||
- $__fish_svn_prompt_char_token_present_display
|
||||
- $__fish_svn_prompt_char_token_present_color
|
||||
|
||||
- $__fish_svn_prompt_char_token_other_display
|
||||
- $__fish_svn_prompt_char_token_other_color
|
||||
|
||||
- $__fish_svn_prompt_char_token_stolen_display
|
||||
- $__fish_svn_prompt_char_token_stolen_color
|
||||
|
||||
- $__fish_svn_prompt_char_token_broken_display
|
||||
- $__fish_svn_prompt_char_token_broken_color
|
||||
|
||||
to choose the color and symbol for different parts of the prompt.
|
||||
|
||||
See also fish_vcs_prompt, which will call all supported vcs-prompt functions, including git, hg and svn.
|
||||
See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -1,27 +1,27 @@
|
|||
.. _cmd-fish_vcs_prompt:
|
||||
|
||||
fish_vcs_prompt - output vcs information for use in a prompt
|
||||
============================================================
|
||||
fish_vcs_prompt - output version control system information for use in a prompt
|
||||
===============================================================================
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
The fish_vcs_prompt function can be used to display information about the current vcs repository, if any.
|
||||
The ``fish_vcs_prompt`` function displays information about the current version control system (VCS) repository, if any.
|
||||
|
||||
It calls out to vcs-specific functions. The currently supported ones are:
|
||||
It calls out to VCS-specific functions. The currently supported systems are:
|
||||
|
||||
- fish_git_prompt
|
||||
- fish_hg_prompt
|
||||
- fish_svn_prompt
|
||||
- :ref:`fish_git_prompt <cmd-fish_git_prompt>`
|
||||
- :ref:`fish_hg_prompt <cmd-fish_hg_prompt>`
|
||||
- :ref:`fish_svn_prompt <cmd-fish_svn_prompt>`
|
||||
|
||||
If a vcs isn't installed, the respective function does nothing.
|
||||
If a VCS isn't installed, the respective function does nothing.
|
||||
|
||||
For more information, see their documentation.
|
||||
For more information, see the documentation for each of the functions above.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
A simple prompt that displays vcs info::
|
||||
A simple prompt that displays all known VCS info::
|
||||
|
||||
function fish_prompt
|
||||
...
|
||||
|
|
|
|||
Loading…
Reference in a new issue