1Ydiff 2===== 3 4.. image:: https://travis-ci.org/ymattw/ydiff.png?branch=master 5 :target: https://travis-ci.org/ymattw/ydiff 6 :alt: Build status 7 8Term based tool to view *colored*, *incremental* diff in a version controlled 9workspace (supports Git, Mercurial, Perforce and Svn so far) or from stdin, 10with *side by side* (similar to ``diff -y``) and *auto pager* support. Requires 11python (>= 2.5.0) and ``less``. 12 13.. image:: https://raw.github.com/ymattw/ydiff/gh-pages/img/default.png 14 :alt: default 15 :align: center 16 17.. image:: https://raw.github.com/ymattw/ydiff/gh-pages/img/side-by-side.png 18 :alt: side by side 19 :align: center 20 :width: 900 px 21 22Installation 23------------ 24 25Install with pip 26~~~~~~~~~~~~~~~~ 27 28Ydiff is already listed on `PyPI`_, you can install with ``pip`` if you have 29the tool. 30 31.. _PyPI: http://pypi.python.org/pypi/ydiff 32 33.. code-block:: bash 34 35 pip install --upgrade ydiff 36 37Install with setup.py 38~~~~~~~~~~~~~~~~~~~~~ 39 40You can also run the setup.py from the source if you don't have ``pip``. 41 42.. code-block:: bash 43 44 git clone https://github.com/ymattw/ydiff.git 45 cd ydiff 46 ./setup.py install 47 48Install with Homebrew 49~~~~~~~~~~~~~~~~~~~~~ 50 51You can also install with Homebrew on Mac. (Thanks to `@josa42`_, 52`@bfontaine`_, `@hivehand`_ and `@nijikon`_ for contributing to the Homebrew 53`Formula`_). 54 55.. _`@josa42`: https://github.com/josa42 56.. _`@bfontaine`: https://github.com/bfontaine 57.. _`@hivehand`: https://github.com/hivehand 58.. _`@nijikon`: https://github.com/nijikon 59.. _`Formula`: https://github.com/Homebrew/homebrew-core/blob/master/Formula/ydiff.rb 60 61.. code-block:: bash 62 63 brew install ydiff 64 65 66Install on Fedora 67~~~~~~~~~~~~~~~~~ 68 69On Fedora, you can install ydiff with dnf. 70 71.. code-block:: bash 72 73 dnf install ydiff 74 75Install on FreeBSD 76~~~~~~~~~~~~~~~~~~ 77 78On FreeBSD, you can install ydiff with pkg. 79 80.. code-block:: bash 81 82 pkg install ydiff 83 84Download directly 85~~~~~~~~~~~~~~~~~ 86 87Just save `ydiff.py`_ to whatever directory which is in your ``$PATH``, for 88example, ``$HOME/bin`` is in my ``$PATH``, so I save the script there and name 89as ``ydiff``. 90 91.. _`ydiff.py`: https://raw.github.com/ymattw/ydiff/master/ydiff.py 92 93.. code-block:: bash 94 95 curl -ksSL https://raw.github.com/ymattw/ydiff/master/ydiff.py > ~/bin/ydiff 96 chmod +x ~/bin/ydiff 97 98Usage 99----- 100 101Type ``ydiff -h`` to show usage:: 102 103 $ ydiff -h 104 Usage: ydiff [options] [file|dir ...] 105 106 View colored, incremental diff in a workspace or from stdin, with side by side 107 and auto pager support 108 109 Options: 110 --version show program's version number and exit 111 -h, --help show this help message and exit 112 -s, --side-by-side enable side-by-side mode 113 -w N, --width=N set text width for side-by-side mode, 0 for auto 114 detection, default is 80 115 -l, --log show log with changes from revision control 116 -c M, --color=M colorize mode 'auto' (default), 'always', or 'never' 117 -t N, --tab-width=N convert tab characters to this many spaces (default: 8) 118 --wrap wrap long lines in side-by-side view 119 -p M, --pager=M pager application, suggested values are 'less' or 'cat' 120 -o M, --pager-options=M 121 options to supply to pager application 122 123 Note: 124 Option parser will stop on first unknown option and pass them down to 125 underneath revision control. Environment variable YDIFF_OPTIONS may be 126 used to specify default options that will be placed at the beginning 127 of the argument list. 128 129Read diff from local modification in a *Git/Mercurial/Perforce/Svn* workspace 130(output from e.g. ``git diff``, ``svn diff``): 131 132.. code-block:: bash 133 134 cd proj-workspace 135 ydiff # view colored incremental diff 136 ydiff -s # view side by side, use default text width 80 137 ydiff -s -w 90 # use text width 90 other than default 80 138 ydiff -s -w 0 # auto set text width based on terminal size 139 ydiff -s -w 0 --wrap # same as before, but also wrap long lines 140 ydiff -s file1 dir2 # view modification of given files/dirs only 141 ydiff -s -w90 --wrap -- -U10 # pass '-U10' to underneath revision diff tool 142 ydiff -s -w90 --wrap -U10 # '--' is optional as it's unknown to ydiff 143 ydiff -s --cached # show git staged diff (git diff --cached) 144 ydiff -s -r1234 # show svn diff to revision 1234 145 146Read log with changes in a *Git/Mercurial/Svn* workspace (output from e.g. 147``git log -p``, ``svn log --diff``), note *--diff* option is new in svn 1.7.0: 148 149.. code-block:: bash 150 151 cd proj-workspace 152 ydiff -l # read log along with changes 153 ydiff -ls # equivalent to ydiff -l -s, view side by side 154 ydiff -ls -w90 --wrap # set text width 90 and enable wrapping as well 155 ydiff -ls file1 dir2 # see log with changes of given files/dirs only 156 157Utilize a specific pager application: 158 159.. code-block:: bash 160 161 ydiff # default pager - less 162 LESS_OPTS='-FRSX --shift 1' 163 ydiff -p less -o "${LESS_OPTS}" # emulate default pager 164 ydiff -p /usr/bin/less # custom pager 165 ydiff -p cat # non-paging ANSI processor for colorizing 166 167Pipe in a diff: 168 169.. code-block:: bash 170 171 git log -p -2 | ydiff # view git log with changes of last 2 commits 172 git show 15bfa | ydiff -s # view a given git commit, side by side 173 svn diff -r1234 | ydiff -s # view svn diff comparing to given revision 174 diff -u file1 file2 | ydiff # view diff between two files (note the '-u') 175 diff -ur dir1 dir2 | ydiff # view diff between two dirs 176 177 # View diff in a GitHub pull request, side by side 178 curl https://github.com/ymattw/ydiff/pull/11.diff | ydiff -s 179 180 # View a patch file in unified or context format, the latter depends on 181 # command `filterdiff` from package `patchutils` which is available in 182 # major Linux distros and MacPorts. 183 # 184 ydiff -s < foo.patch 185 186Redirect output to another patch file is safe: 187 188.. code-block:: bash 189 190 svn diff -r PREV | ydiff -s > my.patch 191 192Environment variable 193-------------------- 194 195Environment variable ``YDIFF_OPTIONS`` may be used to specify default options 196that will be placed at the beginning of the argument list, for example: 197 198.. code-block:: bash 199 200 export YDIFF_OPTIONS='-s -w0 --wrap' 201 ydiff foo # equivalent to "ydiff -s -w0 --wrap foo" 202 203Note the default pager ``less`` takes options from the environment variable 204``LESS``. 205 206Notes 207----- 208 209If you feel more comfortable with a command such as ``git ydiff`` to trigger 210the ydiff command, you may symlink the executable to one named ``git-ydiff`` 211as follows: 212 213.. code-block:: bash 214 215 ydiff_dir=$(dirname $(which ydiff)) 216 ln -s "${ydiff_dir}/ydiff" "${ydiff_dir}/git-ydiff" 217 218Known issues 219------------ 220 221Ydiff has following known issues: 222 223- Does not recognize `normal` diff, and depends on ``filterdiff`` (patchutils) 224 to read `context` diff 225- Side by side mode has alignment problem for wide chars 226- Terminal might be in a mess on exception (type ``reset`` can fix it) 227 228Pull requests are very welcome, please make sure your changes can pass unit 229tests and regression tests by run ``make test`` (required tool *coverage* can 230be installed with ``pip install coverage``). Also watch out `travis build`_ 231after push, make sure it passes as well. 232 233.. _`travis build`: https://travis-ci.org/ymattw/ydiff/pull_requests 234 235See also 236-------- 237 238I have another tool `coderev`_ which generates side-by-side diff pages for code 239review from two given files or directories, I found it's not easy to extend to 240support git so invented `ydiff`. Idea of ansi color markup is also from 241project `colordiff`_. 242 243.. _coderev: https://github.com/ymattw/coderev 244.. _colordiff: https://github.com/daveewart/colordiff 245 246.. vim:set ft=rst et sw=4 sts=4 tw=79: 247
