From 4e0e4dee67fbfb7004b97ca5e0a2658b7a972d1c Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Tue, 12 Nov 2024 19:41:14 +0100 Subject: [PATCH] Polish document --- README.rst | 120 ++++++++++++++++------------------------------------- ydiff.py | 9 ++-- 2 files changed, 39 insertions(+), 90 deletions(-) diff --git a/README.rst b/README.rst index 208903e..82dd91a 100644 --- a/README.rst +++ b/README.rst @@ -5,12 +5,10 @@ Ydiff :alt: Tests status :target: https://github.com/ymattw/ydiff/actions -Term based tool to view *colored*, *incremental* diff in a version controlled -workspace (supports Git, Mercurial, Perforce and Svn so far) or from stdin, -with *side by side* (similar to ``diff -y``) and *auto pager* support. Requires -python >= 3.3 and ``less`` as a pager. - -See screenshots below. +Ydiff is a terminal-based tool to view *colored*, *incremental* diffs in +a version-controlled workspace or from stdin, in *side-by-side* (similar to +``diff -y``) or unified mode, and *auto-paged*. It only requires Python >= 3.3 +*without external dependencies* and ``less`` as a pager. Theme ``default`` on a dark terminal background: @@ -44,31 +42,20 @@ See also `screenshots`_ of unified mode. .. _`screenshots`: https://github.com/ymattw/ydiff/tree/master/img -Ydiff only supports diff in `Unified Format`_. This is default in most version -control system except Perforce, which needs an environment variable -``P4DIFF="diff -u"`` to output unified diff. - -.. _`Unified Format`: https://en.wikipedia.org/wiki/Diff#Unified_format - Installation ------------ Ydiff only depends on Python built-in libraries, so you can just download the -source and run without worrying about any installation. - -Git tagged `releases`_ will be packaged and uploaded to PyPI timely, however, -packages hosted elsewhere are not (please note they are not managed by the -author `@ymattw`_). +source and run without worrying about any installation. Git `tagged`_ revisions +will be packaged and uploaded to `PyPI`_ timely, however, packages hosted +elsewhere are not (please note they are not managed by the author `@ymattw`_). +.. _`tagged`: https://github.com/ymattw/ydiff/tags +.. _`PyPI`: http://pypi.python.org/pypi/ydiff .. _`@ymattw`: https://github.com/ymattw -.. _`releases`: https://github.com/ymattw/ydiff/releases -Download directly -~~~~~~~~~~~~~~~~~ - -Just save `ydiff.py`_ to whatever directory which is in your ``$PATH``, for -example, ``$HOME/bin`` is in my ``$PATH``, so I save the script there and name -as ``ydiff``. +To use the source directly, just save `ydiff.py`_ as ``ydiff`` to whatever +directory which is in your ``$PATH``, for example, ``$HOME/bin``: .. _`ydiff.py`: https://raw.github.com/ymattw/ydiff/master/ydiff.py @@ -77,60 +64,27 @@ as ``ydiff``. curl -L https://raw.github.com/ymattw/ydiff/master/ydiff.py > ~/bin/ydiff chmod +x ~/bin/ydiff -Install with pip -~~~~~~~~~~~~~~~~ - -Ydiff is already listed on `PyPI`_, you can install with ``pip`` if you have -the tool. - -.. _PyPI: http://pypi.python.org/pypi/ydiff +To install from `PyPI`_: .. code-block:: bash pip install --upgrade ydiff -Install with setup.py -~~~~~~~~~~~~~~~~~~~~~ - -You can also run the setup.py from the source if you don't have ``pip``. - -.. code-block:: bash - - git clone https://github.com/ymattw/ydiff.git - cd ydiff - ./setup.py install - -Install with Homebrew -~~~~~~~~~~~~~~~~~~~~~ - -You can also install with Homebrew on Mac. (Thanks to `@josa42`_, -`@bfontaine`_, `@hivehand`_ and `@nijikon`_ for contributing to the Homebrew -`Formula`_). +To install with Homebrew (`Formula`_) on macOS: -.. _`@josa42`: https://github.com/josa42 -.. _`@bfontaine`: https://github.com/bfontaine -.. _`@hivehand`: https://github.com/hivehand -.. _`@nijikon`: https://github.com/nijikon .. _`Formula`: https://github.com/Homebrew/homebrew-core/blob/master/Formula/y/ydiff.rb .. code-block:: bash brew install ydiff - -Install on Fedora -~~~~~~~~~~~~~~~~~ - -On Fedora, you can install ydiff with dnf. +To install on Fedora: .. code-block:: bash dnf install ydiff -Install on FreeBSD -~~~~~~~~~~~~~~~~~~ - -On FreeBSD, you can install ydiff with pkg. +To install on FreeBSD: .. code-block:: bash @@ -234,41 +188,37 @@ Redirect output to another patch file is safe even without ``-u``: svn diff -r PREV | ydiff > my.patch -Environment variable --------------------- +Notes +----- -Environment variable ``YDIFF_OPTIONS`` may be used to specify default options -that will be placed at the beginning of the argument list, for example: +1. Ydiff only supports diffs in `Unified Format`_. This is default in most + version control system except Perforce, which needs an environment variable + ``P4DIFF="diff -u"`` to output unified diff. -.. code-block:: bash + .. _`Unified Format`: https://en.wikipedia.org/wiki/Diff#Unified_format - export YDIFF_OPTIONS='-w100' - ydiff foo # equivalent to "ydiff -w100 foo" +2. Environment variable ``YDIFF_OPTIONS`` may be used to specify default + options that will be placed at the beginning of the argument list, for + example: -Note the default pager ``less`` takes options from the environment variable -``LESS``. + .. code-block:: bash -Notes ------ + export YDIFF_OPTIONS='-w100' + ydiff foo # equivalent to "ydiff -w100 foo" -If you feel more comfortable with a command such as ``git ydiff`` to trigger -the ydiff command, you may symlink the executable to one named ``git-ydiff`` -as follows: +3. If you feel more comfortable with a command such as ``git ydiff`` to trigger + the ydiff command, you may symlink the executable to one named ``git-ydiff`` + as follows: -.. code-block:: bash + .. code-block:: bash - ydiff_dir=$(dirname $(which ydiff)) - ln -s "${ydiff_dir}/ydiff" "${ydiff_dir}/git-ydiff" + installed_dir=$(dirname $(which ydiff)) + ln -s "${installed_dir}/ydiff" "${installed_dir}/git-ydiff" Known issues ------------ -Ydiff has following known issues: - -- Side by side mode has alignment problem for wide chars -- Terminal might be in a mess on exception (type ``reset`` can fix it) - -Pull requests are very welcome, please make sure your changes can pass unit -tests and regression tests by run ``make docker-test``. +- Wide characters may cause alignment problem in side-by-side mode. +- Terminal might be in a mess on exception (type ``reset`` can fix it). .. vim:set ft=rst et sw=4 sts=4 tw=79: diff --git a/ydiff.py b/ydiff.py index 9e6c2e9..f2f1fbb 100755 --- a/ydiff.py +++ b/ydiff.py @@ -2,9 +2,8 @@ # -*- coding: utf-8 -*- """ -Term based tool to view *colored*, *incremental* diff in a *Git/Mercurial/Svn* -workspace or from stdin, with *side by side* and *auto pager* support. Requires -python3 and ``less``. +Terminmal based tool to view colored, incremental diffs in a version-controlled +workspace or from stdin, in side-by-side or unified mode, and auto paged. """ import difflib @@ -18,13 +17,13 @@ from typing import List, Tuple PKG_INFO = { - 'version' : '1.3', + 'version' : '2.0', 'license' : 'BSD-3', 'author' : 'Matt Wang', 'url' : 'https://github.com/ymattw/ydiff', 'keywords' : 'colored incremental side-by-side diff', 'description' : ('View colored, incremental diff in a workspace or from ' - 'stdin, with side by side and auto pager support') + 'stdin, in side-by-side or unified moded, and auto paged') } if sys.hexversion < 0x03030000: