git.iko.soy/bat
on master help sign in
copy README.md (NOT translate yet)
a9acb27sh-tech
doc/README-ja.mdnew file+471
compare with master
unifiedsplit
@@ -0,0 +1,471 @@
1+<p align="center">
2+ <img src="doc/logo-header.svg" alt="bat - a cat clone with wings"><br>
3+ <a href="https://travis-ci.org/sharkdp/bat"><img src="https://travis-ci.org/sharkdp/bat.svg?branch=master" alt="Build Status"></a>
4+ <a href="https://ci.appveyor.com/project/sharkdp/bat"><img src="https://ci.appveyor.com/api/projects/status/cptsmtbiwbnr2vhf?svg=true"></a>
5+ <img src="https://img.shields.io/crates/l/bat.svg" alt="license">
6+ <a href="https://crates.io/crates/bat"><img src="https://img.shields.io/crates/v/bat.svg?colorB=319e8c" alt="Version info"></a><br>
7+ A <i>cat(1)</i> clone with syntax highlighting and Git integration.
8+</p>
9+
10+<p align="center">
11+ <a href="#syntax-highlighting">Key Features</a> •
12+ <a href="#how-to-use">How To Use</a> •
13+ <a href="#installation">Installation</a> •
14+ <a href="#customization">Customization</a> •
15+ <a href="#project-goals-and-alternatives">Project goals, alternatives</a> •
16+ Translation [<a href="https://github.com/chinanf-boy/bat-zh">中文</a>]
17+</p>
18+
19+### Syntax highlighting
20+
21+`bat` supports syntax highlighting for a large number of programming and markup
22+languages:
23+
24+![Syntax highlighting example](https://imgur.com/rGsdnDe.png)
25+
26+### Git integration
27+
28+`bat` communicates with `git` to show modifications with respect to the index
29+(see left side bar):
30+
31+![Git integration example](https://i.imgur.com/2lSW4RE.png)
32+
33+### Show non-printable characters
34+
35+You can use the `-A`/`--show-all` option to show and highlight non-printable
36+characters:
37+
38+![Non-printable character example](https://i.imgur.com/WndGp9H.png)
39+
40+### Automatic paging
41+
42+`bat` can pipe its own output to `less` if the output is too large for one screen.
43+
44+### File concatenation
45+
46+Oh.. you can also use it to concatenate files :wink:. Whenever
47+`bat` detects a non-interactive terminal (i.e. when you pipe into another process
48+or into a file), `bat` will act as a drop-in replacement for `cat` and
49+fall back to printing the plain file contents.
50+
51+## How to use
52+
53+Display a single file on the terminal
54+
55+```bash
56+> bat README.md
57+```
58+
59+Display multiple files at once
60+
61+```bash
62+> bat src/*.rs
63+```
64+
65+Read from stdin, determine the syntax automatically
66+
67+```bash
68+> curl -s https://sh.rustup.rs | bat
69+```
70+
71+Read from stdin, specify the language explicitly
72+
73+```bash
74+> yaml2json .travis.yml | json_pp | bat -l json
75+```
76+
77+Show and highlight non-printable characters:
78+```bash
79+> bat -A /etc/hosts
80+```
81+
82+Use it as a `cat` replacement:
83+
84+```bash
85+bat > note.md # quickly create a new file
86+
87+bat header.md content.md footer.md > document.md
88+
89+bat -n main.rs # show line numbers (only)
90+
91+bat f - g # output 'f', then stdin, then 'g'.
92+```
93+
94+## Installation
95+
96+### On Ubuntu
97+*... and other Debian-based Linux distributions.*
98+
99+Download the latest `.deb` package from the [release page](https://github.com/sharkdp/bat/releases)
100+and install it via:
101+``` bash
102+sudo dpkg -i bat_0.9.0_amd64.deb # adapt version number and architecture
103+```
104+
105+### On Arch Linux
106+
107+You can install [the `bat` package](https://www.archlinux.org/packages/community/x86_64/bat/)
108+from the official sources:
109+
110+```bash
111+pacman -S bat
112+```
113+
114+### On Void Linux
115+
116+You can install `bat` via xbps-install:
117+```
118+xbps-install -S bat
119+```
120+
121+### On FreeBSD
122+
123+You can install a precompiled [`bat` package](https://www.freshports.org/textproc/bat) with pkg:
124+
125+```bash
126+pkg install bat
127+```
128+
129+or build it on your own from the FreeBSD ports:
130+
131+```bash
132+cd /usr/ports/textproc/bat
133+make install
134+```
135+
136+### Via nix
137+
138+You can install `bat` using the [nix package manager](https://nixos.org/nix):
139+
140+```bash
141+nix-env -i bat
142+```
143+
144+### On openSUSE
145+
146+You can install `bat` with zypper:
147+
148+```
149+zypper install bat
150+```
151+
152+### On macOS
153+
154+You can install `bat` with [Homebrew](http://braumeister.org/formula/bat):
155+
156+```bash
157+brew install bat
158+```
159+
160+### On Windows
161+
162+You can download prebuilt binaries from the [Release page](https://github.com/sharkdp/bat/releases),
163+or install it with [scoop](https://scoop.sh/):
164+
165+```bash
166+scoop install bat
167+```
168+
169+[See below](#using-bat-on-windows) for notes.
170+
171+### Via Docker
172+
173+There is a [Docker image](https://hub.docker.com/r/danlynn/bat/) that you can use to run `bat` in a container:
174+```bash
175+docker pull danlynn/bat
176+alias bat='docker run -it --rm -e BAT_THEME -e BAT_STYLE -e BAT_TABS -v "$(pwd):/myapp" danlynn/bat'
177+```
178+
179+### Via Ansible
180+
181+You can install `bat` with [Ansible](https://www.ansible.com/):
182+
183+```bash
184+# Install role on local machine
185+ansible-galaxy install aeimer.install_bat
186+```
187+
188+```yaml
189+---
190+# Playbook to install bat
191+- host: all
192+ roles:
193+ - aeimer.install_bat
194+```
195+
196+- [Ansible Galaxy](https://galaxy.ansible.com/aeimer/install_bat)
197+- [GitHub](https://github.com/aeimer/ansible-install-bat)
198+
199+This should work with the following distributions:
200+- Debian/Ubuntu
201+- ARM (eg. Raspberry PI)
202+- Arch Linux
203+- Void Linux
204+- FreeBSD
205+- MacOS
206+
207+### From binaries
208+
209+Check out the [Release page](https://github.com/sharkdp/bat/releases) for
210+prebuilt versions of `bat` for many different architectures. Statically-linked
211+binaries are also available: look for archives with `musl` in the file name.
212+
213+### From source
214+
215+If you want to build `bat` from source, you need Rust 1.29 or
216+higher. You can then use `cargo` to build everything:
217+
218+```bash
219+cargo install bat
220+```
221+
222+You may have to install `cmake` and the `libz` development package
223+(`libz-dev` or `libz-devel`) in order for the build to succeed.
224+
225+## Customization
226+
227+### Highlighting theme
228+
229+Use `bat --list-themes` to get a list of all available themes for syntax
230+highlighting. To select the `TwoDark` theme, call `bat` with the
231+`--theme=TwoDark` option or set the `BAT_THEME` environment variable to
232+`TwoDark`. Use `export BAT_THEME="TwoDark"` in your shell's startup file to
233+make the change permanent. Alternatively, use `bat`s
234+[configuration file](https://github.com/sharkdp/bat#configuration-file).
235+
236+If you want to preview the different themes on a custom file, you can use
237+the following command (you need [`fzf`](https://github.com/junegunn/fzf) for this):
238+``` bash
239+bat --list-themes | fzf --preview="bat --theme={} --color=always /path/to/file"
240+```
241+
242+`bat` looks good on a dark background by default. However, if your terminal uses a
243+light background, some themes like `GitHub` or `OneHalfLight` will work better for you.
244+You can also use a custom theme by following the
245+['Adding new themes' section below](https://github.com/sharkdp/bat#adding-new-themes).
246+
247+### Output style
248+
249+You can use the `--style` option to control the appearance of `bat`s output.
250+You can use `--style=numbers,changes`, for example, to show only Git changes
251+and line numbers but no grid and no file header. Set the `BAT_STYLE` environment
252+variable to make these changes permanent or use `bat`s
253+[configuration file](https://github.com/sharkdp/bat#configuration-file).
254+
255+### Adding new syntaxes / language definitions
256+
257+`bat` uses the excellent [`syntect`](https://github.com/trishume/syntect/)
258+library for syntax highlighting. `syntect` can read any
259+[Sublime Text `.sublime-syntax` file](https://www.sublimetext.com/docs/3/syntax.html)
260+and theme. To add new syntax definitions, do the following.
261+
262+Create a folder with syntax definition files:
263+
264+```bash
265+BAT_CONFIG_DIR="$(bat cache --config-dir)"
266+
267+mkdir -p "$BAT_CONFIG_DIR/syntaxes"
268+cd "$BAT_CONFIG_DIR/syntaxes"
269+
270+# Put new '.sublime-syntax' language definition files
271+# in this folder (or its subdirectories), for example:
272+git clone https://github.com/tellnobody1/sublime-purescript-syntax
273+```
274+
275+Now use the following command to parse these files into a binary cache:
276+
277+```bash
278+bat cache --init
279+```
280+
281+Finally, use `bat --list-languages` to check if the new languages are available.
282+
283+If you ever want to go back to the default settings, call:
284+
285+```bash
286+bat cache --clear
287+```
288+
289+### Adding new themes
290+
291+This works very similar to how we add new syntax definitions.
292+
293+First, create a folder with the new syntax highlighting themes:
294+```bash
295+BAT_CONFIG_DIR="$(bat cache --config-dir)"
296+
297+mkdir -p "$BAT_CONFIG_DIR/themes"
298+cd "$BAT_CONFIG_DIR/themes"
299+
300+# Download a theme in '.tmTheme' format, for example:
301+git clone https://github.com/greggb/sublime-snazzy
302+
303+# Update the binary cache
304+bat cache --init
305+```
306+
307+Finally, use `bat --list-themes` to check if the new themes are available.
308+
309+### Using a different pager
310+
311+`bat` uses the pager that is specified in the `PAGER` environment variable. If this variable is not
312+set, `less` is used by default. If you want to use a different pager, you can either modify the
313+`PAGER` variable or set the `BAT_PAGER` environment variable to override what is specified in
314+`PAGER`.
315+
316+If you want to pass command-line arguments to the pager, you can also set them via the
317+`PAGER`/`BAT_PAGER` variables:
318+
319+```bash
320+export BAT_PAGER="less -RF"
321+```
322+
323+Instead of using environment variables, you can also use `bat`s [configuration file](https://github.com/sharkdp/bat#configuration-file) to configure the pager (`--pager` option).
324+
325+**Note**: By default, if the pager is set to `less` (any no command-line options are specified),
326+`bat` will pass the following command line
327+options to the pager: `-R`/`--RAW-CONTROL-CHARS`, `-F`/`--quit-if-one-screen` and `-X`/`--no-init`.
328+The first (`-R`) is needed to interpret ANSI colors correctly. The second option (`-F`) instructs
329+less to exit immediately if the output size is smaller than the vertical size of the terminal.
330+This is convenient for small files because you do not have to press `q` to quit the pager. The
331+third option (`-X`) is needed to fix a bug with the `--quit-if-one-screen` feature in old versions
332+of `less`. Unfortunately, it also breaks mouse-wheel support in `less`. If you want to enable
333+mouse-wheel scrolling, you can either pass just `-R` (as in the example above, this will disable
334+the quit-if-one-screen feature), or you can use a recent version of `less` and pass `-RF` which
335+will hopefully enable both quit-if-one-screen and mouse-wheel scrolling.
336+
337+If scrolling still doesn't work for you, you can try to pass the `-S` option in addition.
338+
339+## Configuration file
340+
341+`bat` can also be customized with a configuration file. The location of the file is dependent
342+on your operating system. To get the default path for your system, call
343+```
344+bat --config-file
345+```
346+
347+Alternatively, you can use the `BAT_CONFIG_PATH` environment variable to point `bat` to a
348+non-default location of the configuration file:
349+```bash
350+export BAT_CONFIG_PATH="/path/to/bat.conf"
351+```
352+
353+### Format
354+
355+The configuration file is a simple list of command line arguments. Use `bat --help` to see a full list of possible options and values. In addition, you can add comments by prepending a line with the `#` character.
356+
357+Example configuration file:
358+```bash
359+# Set the theme to "TwoDark"
360+--theme="TwoDark"
361+
362+# Show line numbers, Git modifications and file header (but no grid)
363+--style="numbers,changes,header"
364+
365+# Use italic text on the terminal (not supported on all terminals)
366+--italic-text=always
367+
368+# Add mouse scrolling support in less (does not work with older
369+# versions of "less")
370+--pager="less -FR"
371+
372+# Use C++ syntax (instead of C) for .h header files
373+--map-syntax h:cpp
374+
375+# Use "gitignore" highlighting for ".ignore" files
376+--map-syntax .ignore:.gitignore
377+```
378+
379+## Using `bat` on Windows
380+
381+`bat` mostly works out-of-the-box on Windows, but a few features may need extra configuration.
382+
383+### Paging
384+
385+Windows only includes a very limited pager in the form of `more`. You can download a Windows binary
386+for `less` [from its homepage](http://www.greenwoodsoftware.com/less/download.html) or [through
387+Chocolatey](https://chocolatey.org/packages/Less). To use it, place the binary in a directory in
388+your `PATH` or [define an environment variable](#using-a-different-pager).
389+
390+### Colours
391+
392+Windows 10 natively supports colours in both `conhost.exe` (Command Prompt) and PowerShell since
393+[v1511](https://en.wikipedia.org/wiki/Windows_10_version_history#Version_1511_(November_Update)), as
394+well as in newer versions of bash. On earlier versions of Windows, you can use
395+[Cmder](http://cmder.net/), which includes [ConEmu](https://conemu.github.io/).
396+
397+**Note:** The Git and MSYS versions of `less` do not correctly interpret colours on Windows. If you
398+don’t have any other pagers installed, you can disable paging entirely by passing `--paging=never`
399+or by setting `BAT_PAGER` to an empty string.
400+
401+### Cygwin
402+
403+`bat` on Windows does not natively support Cygwin's unix-style paths (`/cygdrive/*`). When passed an absolute cygwin path as an argument, `bat` will encounter the following error: `The system cannot find the path specified. (os error 3)`
404+
405+This can be solved by creating a wrapper or adding the following function to your `.bash_profile` file:
406+
407+```shell
408+bat() {
409+ local index
410+ local args=("$@")
411+ for index in $(seq 0 ${#args[@]}) ; do
412+ case "${args[index]}" in
413+ -*) continue;;
414+ *) [ -e "${args[index]}" ] && args[index]="$(cygpath --windows "${args[index]}")";;
415+ esac
416+ done
417+ command bat "${args[@]}"
418+}
419+```
420+
421+## Troubleshooting
422+
423+### Terminals & colors
424+
425+`bat` handles terminals *with* and *without* truecolor support. However, the colors in the syntax
426+highlighting themes are not optimized for 8-bit colors and it is therefore strongly recommended
427+that you use a terminal with 24-bit truecolor support (`terminator`, `konsole`, `iTerm2`, ...).
428+See [this article](https://gist.github.com/XVilka/8346728) for more details and a full list of
429+terminals with truecolor support.
430+
431+Make sure that your truecolor terminal sets the `COLORTERM` variable to either `truecolor` or
432+`24bit`. Otherwise, `bat` will not be able to determine whether or not 24-bit escape sequences
433+are supported (and fall back to 8-bit colors).
434+
435+### Line numbers and grid are hardly visible
436+
437+Please try a different theme (see `bat --list-themes` for a list). The `OneHalfDark` and
438+`OneHalfLight` themes provide grid and line colors that are brighter.
439+
440+## Development
441+
442+```bash
443+# Recursive clone to retrieve all submodules
444+git clone --recursive https://github.com/sharkdp/bat
445+
446+# Build (debug version)
447+cd bat
448+cargo build
449+
450+# Run unit tests and integration tests
451+cargo test
452+
453+# Install (release version)
454+cargo install
455+
456+# Build a bat binary with modified syntaxes and themes
457+bash assets/create.sh
458+cargo install -f
459+```
460+
461+## Project goals and alternatives
462+
463+`bat` tries to achieve the following goals:
464+
465+- Provide beautiful, advanced syntax highlighting
466+- Integrate with Git to show file modifications
467+- Be a drop-in replacement for (POSIX) `cat`
468+- Offer a user-friendly command-line interface
469+
470+There are a lot of alternatives, if you are looking for similar programs. See
471+[this document](doc/alternatives.md) for a comparison.