← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/plugins/bash_completion/README.txt

  • Committer: Martin Pool
  • Date: 2005-07-28 11:56:24 UTC
  • Revision ID: mbp@sourcefrog.net-20050728115624-93c11c2b1e399023
- note changes to command line parsing

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/plugins/bash_completion/README.txt
1
 
.. comment
2
 
 
3
 
  Copyright (C) 2010 Canonical Ltd
4
 
 
5
 
  This file is part of bzr-bash-completion
6
 
 
7
 
  bzr-bash-completion free software: you can redistribute it and/or
8
 
  modify it under the terms of the GNU General Public License as
9
 
  published by the Free Software Foundation, either version 2 of the
10
 
  License, or (at your option) any later version.
11
 
 
12
 
  bzr-bash-completion is distributed in the hope that it will be
13
 
  useful, but WITHOUT ANY WARRANTY; without even the implied warranty
14
 
  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15
 
  General Public License for more details.
16
 
 
17
 
  You should have received a copy of the GNU General Public License
18
 
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
19
 
 
20
 
=====================================
21
 
bzr bash-completion script and plugin
22
 
=====================================
23
 
 
24
 
This script generates a shell function which can be used by bash to
25
 
automatically complete the currently typed command when the user
26
 
presses the completion key (usually tab).
27
 
 
28
 
It is intended as a bzr plugin, but can be used to some extend as a
29
 
standalone python script as well.
30
 
 
31
 
| Copyright (C) 2009, 2010 Canonical Ltd
32
 
 
33
 
.. contents::
34
 
 
35
 
----------
36
 
Installing
37
 
----------
38
 
 
39
 
You only need to do this if you want to use the script as a bzr
40
 
plugin.  Otherwise simply grab the bashcomp.py and place it wherever
41
 
you want.
42
 
 
43
 
Installing from bzr repository
44
 
------------------------------
45
 
 
46
 
To check out the current code from launchpad, use the following commands::
47
 
 
48
 
  mkdir -p ~/.bazaar/plugins
49
 
  cd ~/.bazaar/plugins
50
 
  bzr checkout lp:bzr-bash-completion bash_completion
51
 
 
52
 
To update such an installation, execute this command::
53
 
 
54
 
  bzr update ~/.bazaar/plugins/bash_completion
55
 
 
56
 
Installing using easy_install
57
 
-----------------------------
58
 
 
59
 
The following command should install the latest release of the plugin
60
 
on your system::
61
 
 
62
 
  easy_install bzr-bash-completion
63
 
 
64
 
To use this method, you need to have `Easy Install`_ installed and
65
 
also have write access to the required directories. So maybe you
66
 
should execute this command as root or through sudo_. Or you want to
67
 
`install to a different location`_.
68
 
 
69
 
.. _Easy Install: http://peak.telecommunity.com/DevCenter/EasyInstall
70
 
.. _sudo: http://linux.die.net/man/8/sudo
71
 
.. _install to a different location:
72
 
   http://peak.telecommunity.com/DevCenter/EasyInstall#non-root-installation
73
 
 
74
 
Installing from tarball
75
 
-----------------------
76
 
 
77
 
If you have grabbed a source code tarball, or want to install from a
78
 
bzr checkout in a different place than your bazaar plugins directory,
79
 
then you should use the ``setup.py`` script shipped with the code::
80
 
 
81
 
  ./setup.py install
82
 
 
83
 
If you want to install the plugin only for your own user account, you
84
 
might wish to pass the option ``--user`` or ``--home=$HOME`` to that
85
 
command. For further information please read the manuals of distutils_
86
 
as well as setuptools_ or distribute_, whatever is available on your
87
 
system, or have a look at the command line help::
88
 
 
89
 
  ./setup.py install --help
90
 
 
91
 
.. _distutils: http://docs.python.org/install/index.html
92
 
.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools#what-your-users-should-know
93
 
.. _distribute: http://packages.python.org/distribute/setuptools.html#what-your-users-should-know
94
 
 
95
 
-----
96
 
Using
97
 
-----
98
 
 
99
 
Using as a plugin
100
 
-----------------
101
 
 
102
 
This is the preferred method of generating the completion function, as
103
 
it will ensure proper bzr initialization.
104
 
 
105
 
::
106
 
 
107
 
  eval "`bzr bash-completion`"
108
 
 
109
 
Lazy initialization
110
 
-------------------
111
 
 
112
 
Running the above command automatically from your ``~/.bashrc`` file
113
 
or similar can cause annoying delays in the startup of your shell.
114
 
To avoid this problem, you can delay the generation of the completion
115
 
function until you actually need it.
116
 
 
117
 
To do so, source the file ``lazy.sh`` shipped with this package from
118
 
your ``~/.bashrc`` file or add it to your ``~/.bash_completion`` if
119
 
your setup uses such a file. On a system-wide installation, the
120
 
directory ``/usr/share/bash-completion/`` might contain such bash
121
 
completion scripts.
122
 
 
123
 
If you installed bzr-bash-completion from the repository or a source
124
 
tarball, you find the ``lazy.sh`` script in the root of the source
125
 
tree. If you installed the plugin using easy_install, you should grab
126
 
the script manually from the bzr repository, e.g. through the bazaar
127
 
web interface on launchpad.
128
 
 
129
 
Note that the full completion function is generated only once per
130
 
shell session. If you update your bzr installation or change the set
131
 
of installed plugins, then you might wish to regenerate the completion
132
 
function manually as described above in order for completion to take
133
 
these changes into account.
134
 
 
135
 
Using as a script
136
 
-----------------
137
 
 
138
 
As an alternative, if bzrlib is available to python scripts, the
139
 
following invocation should yield the same results without requiring
140
 
you to add a plugin::
141
 
 
142
 
  eval "`./bashcomp.py`"
143
 
 
144
 
This approach might have some issues, though, and provides less
145
 
options than the bzr plugin. Therefore if you have the choice, go for
146
 
the plugin setup.
147
 
 
148
 
--------------
149
 
Design concept
150
 
--------------
151
 
 
152
 
The plugin (or script) is designed to generate a completion function
153
 
containing all the required information about the possible
154
 
completions. This is usually only done once when bash
155
 
initializes. After that, no more invocations of bzr are required. This
156
 
makes the function much faster than a possible implementation talking
157
 
to bzr for each and every completion. On the other hand, this has the
158
 
effect that updates to bzr or its plugins won't show up in the
159
 
completions immediately, but only after the completion function has
160
 
been regenerated.
161
 
 
162
 
-------
163
 
License
164
 
-------
165
 
 
166
 
As this is built upon a bash completion script originally included in
167
 
the bzr source tree, and as the bzr sources are covered by the GPL 2,
168
 
this script here is licensed under these same terms.
169
 
 
170
 
If you require a more liberal license, you'll have to contact all
171
 
those who contributed code to this plugin, be it for bash or for
172
 
python.
173
 
 
174
 
.. cut long_description here
175
 
 
176
 
-------
177
 
History
178
 
-------
179
 
 
180
 
The plugin was created by Martin von Gagern in 2009, building on a
181
 
static completion function of very limited scope distributed together
182
 
with bzr.
183
 
 
184
 
----------
185
 
References
186
 
----------
187
 
 
188
 
Plugin homepages
189
 
  | https://launchpad.net/bzr-bash-completion
190
 
  | http://pypi.python.org/pypi/bzr-bash-completion
191
 
Bazaar homepage
192
 
  | http://bazaar.canonical.com/
193
 
 
194
 
 
195
 
 
196
 
.. vim: ft=rst
197
 
 
198
 
.. emacs
199
 
   Local Variables:
200
 
   mode: rst
201
 
   End: