← 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: Marius Kruger
  • Date: 2010-07-10 21:28:56 UTC
  • mto: (5384.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 5385.
  • Revision ID: marius.kruger@enerweb.co.za-20100710212856-uq4ji3go0u5se7hx
* Update documentation
* add NEWS

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 plugin
 
22
==========================
 
23
 
 
24
This plugin 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
Bundled and standalone versions
 
37
-------------------------------
 
38
 
 
39
This plugin has been merged_ into the main source tree of Bazaar.
 
40
Starting with the bzr 2.3 series, a common bzr installation will
 
41
include this plugin.
 
42
 
 
43
There is still a standalone version available. It makes the plugin
 
44
available for users of older bzr versions. When using both versions,
 
45
local configuration might determine which version actually gets used,
 
46
and some installations might even overwrite one another, so don't use
 
47
the standalone version if you have the bundled one, unless you know
 
48
what you are doing. Some effort will be made to keep the two versions
 
49
reasonably in sync for some time yet.
 
50
 
 
51
This text here documents the bundled version.
 
52
 
 
53
.. _merged: http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/revision/5240
 
54
 
 
55
-----
 
56
Using
 
57
-----
 
58
 
 
59
Using as a plugin
 
60
-----------------
 
61
 
 
62
This is the preferred method of generating the completion function, as
 
63
it will ensure proper bzr initialization.
 
64
 
 
65
::
 
66
 
 
67
  eval "`bzr bash-completion`"
 
68
 
 
69
Lazy initialization
 
70
-------------------
 
71
 
 
72
Running the above command automatically from your ``~/.bashrc`` file
 
73
or similar can cause annoying delays in the startup of your shell.
 
74
To avoid this problem, you can delay the generation of the completion
 
75
function until you actually need it.
 
76
 
 
77
To do so, source the file ``contrib/bash/bzr`` shipped with the bzr
 
78
source distribution from your ``~/.bashrc`` file
 
79
or add it to your ``~/.bash_completion`` if
 
80
your setup uses such a file. On a system-wide installation, the
 
81
directory ``/usr/share/bash-completion/`` might contain such bash
 
82
completion scripts.
 
83
 
 
84
Note that the full completion function is generated only once per
 
85
shell session. If you update your bzr installation or change the set
 
86
of installed plugins, then you might wish to regenerate the completion
 
87
function manually as described above in order for completion to take
 
88
these changes into account.
 
89
 
 
90
--------------
 
91
Design concept
 
92
--------------
 
93
 
 
94
The plugin is designed to generate a completion function
 
95
containing all the required information about the possible
 
96
completions. This is usually only done once when bash
 
97
initializes. After that, no more invocations of bzr are required. This
 
98
makes the function much faster than a possible implementation talking
 
99
to bzr for each and every completion. On the other hand, this has the
 
100
effect that updates to bzr or its plugins won't show up in the
 
101
completions immediately, but only after the completion function has
 
102
been regenerated.
 
103
 
 
104
-------
 
105
License
 
106
-------
 
107
 
 
108
As this is built upon a bash completion script originally included in
 
109
the bzr source tree, and as the bzr sources are covered by the GPL 2,
 
110
this plugin here is licensed under these same terms.
 
111
 
 
112
If you require a more liberal license, you'll have to contact all
 
113
those who contributed code to this plugin, be it for bash or for
 
114
python.
 
115
 
 
116
-------
 
117
History
 
118
-------
 
119
 
 
120
The plugin was created by Martin von Gagern in 2009, building on a
 
121
static completion function of very limited scope distributed together
 
122
with bzr.
 
123
 
 
124
A version of it was merged into the bzr source tree in May 2010.
 
125
 
 
126
----------
 
127
References
 
128
----------
 
129
 
 
130
Bazaar homepage
 
131
  | http://bazaar.canonical.com/
 
132
Standalone plugin homepages
 
133
  | https://launchpad.net/bzr-bash-completion
 
134
  | http://pypi.python.org/pypi/bzr-bash-completion
 
135
 
 
136
 
 
137
 
 
138
.. vim: ft=rst
 
139
 
 
140
.. emacs
 
141
   Local Variables:
 
142
   mode: rst
 
143
   End: