code.delx.au - gnu-emacs-elpa/blob - packages/ivy/README.md

   1 [![Build Status](https://travis-ci.org/abo-abo/swiper.svg?branch=master)](https://travis-ci.org/abo-abo/swiper) [![MELPA](https://melpa.org/packages/swiper-badge.svg)](https://melpa.org/#/swiper)
   2
   3 ## Swiper
   4
   5 Package for GNU Emacs that shows an overview during regex searching.
   6
   7 ![swiper.png](http://oremacs.com/download/swiper.png)
   8
   9 The package uses the `ivy` back end for the overview, see also
  10 [swiper-helm](https://github.com/abo-abo/swiper-helm).
  11
  12 ## Screenshots
  13
  14 ![ivy-swiper-1.png](http://oremacs.com/download/ivy-swiper-1.png)
  15
  16 There's also a ten minute [video demo](https://www.youtube.com/watch?v=VvnJQpTFVDc).
  17
  18 ## Ivy
  19
  20 Ivy is a generic completion mechanism for Emacs. While it operates
  21 similarly to other completion schemes such as `icomplete-mode`, Ivy
  22 aims to be more efficient, smaller, simpler, and smoother to use yet
  23 highly customizable.
  24
  25 To try Ivy, just call <kbd>M-x</kbd> `ivy-mode`. This will enable
  26 generic Ivy completion, including specific completion for file and
  27 buffer names.
  28
  29 ## Installation
  30
  31 Install the `swiper` package from MELPA / GNU ELPA.
  32
  33 ## Documentation
  34
  35 ### Manual
  36 The manual is available as [HTML](http://oremacs.com/swiper/).
  37
  38 After installing from MELPA, the manual is also available through the `(ivy)` Info node.
  39
  40 The source file for the Info page is
  41 [here](https://github.com/abo-abo/swiper/blob/master/doc/ivy.org).
  42
  43 ### Wiki
  44 Ivy and Swiper wiki is here: [the wiki](https://github.com/abo-abo/swiper/wiki).
  45
  46 ### Small config example
  47 ```elisp
  48 (ivy-mode 1)
  49 (setq ivy-use-virtual-buffers t)
  50 (global-set-key "\C-s" 'swiper)
  51 (global-set-key (kbd "C-c C-r") 'ivy-resume)
  52 (global-set-key (kbd "<f6>") 'ivy-resume)
  53 (global-set-key (kbd "M-x") 'counsel-M-x)
  54 (global-set-key (kbd "C-x C-f") 'counsel-find-file)
  55 (global-set-key (kbd "<f1> f") 'counsel-describe-function)
  56 (global-set-key (kbd "<f1> v") 'counsel-describe-variable)
  57 (global-set-key (kbd "<f1> l") 'counsel-load-library)
  58 (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
  59 (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
  60 (global-set-key (kbd "C-c g") 'counsel-git)
  61 (global-set-key (kbd "C-c j") 'counsel-git-grep)
  62 (global-set-key (kbd "C-c k") 'counsel-ag)
  63 (global-set-key (kbd "C-x l") 'counsel-locate)
  64 (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
  65 (define-key read-expression-map (kbd "C-r") 'counsel-expression-history)
  66 ```
  67
  68 ## Contributing
  69
  70 ### Copyright Assignment
  71
  72 Swiper is subject to the same [copyright assignment](http://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html) policy as Emacs itself, org-mode, CEDET and other packages in [GNU ELPA](http://elpa.gnu.org/packages/). Any [legally significant](http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant) contributions can only be accepted after the author has completed their paperwork. Please see [the request form](http://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future) if you want to proceed.
  73
  74 The copyright assignment isn't a big deal, it just says that the copyright for your submitted changes to Emacs belongs to the FSF. This assignment works for all projects related to Emacs. To obtain it, you need to send one email, then send one letter (if you live in the US, it's digital), and wait for some time (in my case, I had to wait for one month).
  75
  76 ### Style
  77
  78 The basic code style guide is to use `(setq indent-tabs-mode nil)`. It is provided for you in [.dir-locals.el](https://github.com/abo-abo/swiper/blob/master/.dir-locals.el), please obey it.
  79
  80 Before submitting the change, run `make compile` and `make test` to make sure that it doesn't introduce new compile warnings or test failures. Also run <kbd>M-x</kbd> `checkdoc` to see that your changes obey the documentation guidelines.
  81
  82 Use your own judgment for the commit messages, I recommend a verbose style using `magit-commit-add-log`.