src/chere.1

   1
   2 .TH chere 1 "Sep 2007" "User Commands"
   3 .SH NAME
   4 chere \- manage Shell Here context menu items
   5 .SH SYNOPSIS
   6 .B chere
   7 .RB \-<iuxlrhv>
   8 .RB [ \-lracnmpf12 ]
   9 .RB [ \-t
  10 .IR term ]
  11 .RB [ \-s
  12 .IR shell ]
  13 .RB [ \-d
  14 .IR display ]
  15 .RB [ \-o
  16 .IR options ]
  17 .RB [ \-e
  18 .IR menutext ]
  19
  20 .SH DESCRIPTION
  21 .B chere
  22 adds the
  23 .I term
  24 /
  25 .I shell
  26 combination to the folder context menu. This allows you to right click a folder in Windows Explorer and open
  27 .I shell
  28 in that folder.
  29 .PP
  30 Where possible, a login shell will be started. i.e. login scripts (
  31 .B /etc/profile, ~/profile, ~/.bash_profile, ~/.bash_login, /etc/csh.login, /etc/zprofile, $ZDOTDIR/.zprofile /etc/zlogin $ZDOTDIR/.zlogin
  32 ) are run as appropriate for the shell. This does not apply to cmd, which does not have any login scripts.
  33 .PP
  34 The title of the window is not set. It will default to whatever the terminal sets it to. This can usually be controlled from the shell by passing an escape sequence to the shell.
  35 .SH OPTIONS
  36 .TP
  37 .B \-\^i
  38 Install
  39 .TP
  40 .B \-\^u
  41 Uninstall
  42 .TP
  43 .B \-\^x
  44 Refresh eXisting context menu items
  45 .TP
  46 .B \-\^l
  47 List currently installed Shell Here
  48 .TP
  49 .B \-\^r
  50 Read all
  51 .B chere
  52 registry entries to stdout
  53 .TP
  54 .B \-\^a
  55 Operation affects all users
  56 .TP
  57 .B \-\^c
  58 Operation affects current user only
  59 .TP
  60 .B \-\^n
  61 Be Nice and provide Control Panel uninstall option (Default)
  62 .TP
  63 .B \-\^m
  64 Minimal, no Control Panel uninstall
  65 .TP
  66 .B \-\^p
  67 Print
  68 .B regtool
  69 commands to stdout rather than running them
  70 .TP
  71 .B \-\^f
  72 Force write (overwrite existing, ignore missing files)
  73 .TP
  74 .B \-\^1
  75 Start shell using registry one-liners. This doesn\'t work with ash, tcsh or network shares.
  76 .TP
  77 .B \-\^2
  78 Start via
  79 .B bash
  80 script. Relies on windows to change directory, and login scripts avoiding doing a cd
  81 .B $HOME
  82 .TP
  83 .B \-\^d display
  84 Specifies the display to use if xterm is specified as the shell. Defaults to :0. If set to env, then the environment variable
  85 .B DISPLAY
  86 is read when the context menu item is selected.
  87 .TP
  88 .B \-\^o options
  89 Add
  90 .IR options
  91 to the terminal startup command. If more than one option is specified, they should all be contained within a single set of quotes.
  92
  93 .TP
  94 .B \-\^e menutext
  95 Use
  96 .IR menutext
  97 as the context menu text.
  98
  99 .TP
 100 .B \-\^h
 101 Help
 102 .TP
 103 .B \-\^v
 104 Version
 105 .PP
 106 Supported terminals:
 107 .B cmd rxvt xterm
 108 .PP
 109 Supported shells:
 110 .B ash bash cmd pdksh tcsh zsh passwd
 111
 112 .SH USAGE
 113 .PP
 114 A command (
 115 .B -iuxlrhv
 116 ) must be specified before
 117 .B chere
 118 does anything. All other options modify how these commands work.
 119 .PP
 120 The
 121 .B -i
 122 (install) and
 123 .B -u
 124 (uninstall) commands are mutually exclusive. The
 125 .B -l
 126 and
 127 .B -r
 128 commands may be specified in addition to
 129 .B -i
 130 ,
 131 .B -u
 132 or
 133 .B -x
 134 , in which case the read/list is done after the install/uninstall/refresh.
 135
 136 .PP
 137 The context menu may be (un)installed for all users
 138 .B \-\^a
 139 , or just yourself
 140 .B \-\^c.
 141 To (un)install for all users, you will require appropriate access rights. i.e. you need to have Administrator rights.
 142
 143 .PP
 144 If the -i flag is passed without specifying a shell, the shell specified in
 145 .B /etc/passwd
 146 for the current user is added. If
 147 .B term
 148 is not specified,
 149 .B cmd
 150 is used.
 151
 152 .PP
 153 If the
 154 .B -u
 155 flag is passed without specifying a shell, all installed context menus will be uninstalled. If
 156 .B -a
 157 or
 158 .B -c
 159 is also specified, only the context menus for the specified users are uninstalled. Otherwise the context menus are removed for all users and the current user.
 160
 161 .PP
 162 It is not possible to uninstall a context menu for a user who is not the current user.
 163
 164 .PP
 165 The
 166 .B passwd
 167 shell tries to determine your preferred shell at runtime from your
 168 .B /etc/passwd
 169 entry. This is most useful on multi-user systems.
 170
 171 .PP
 172 By default, registry entries are added so that the context menus can be removed using the Add Remove Programs utility in the Windows Control Panel. The
 173 .B -m
 174 option prevents this. Note that this uninstall option invokes
 175 .B chere.
 176 When installing for the current user,
 177 .B chere
 178 will attempt to set an uninstall entry. If the user does not have appropriate rights to add keys to the HKLM hive, then the uninstall will not be present. Using
 179 .B -m
 180 will avoid the error message.
 181
 182 .PP
 183 The
 184 .B -1
 185 and
 186 .B -2
 187 options select how
 188 .B shell
 189 is started. The original method (
 190 .B -1
 191 ) of registry one-liners is succint, but does not work on network shares or with
 192 .B ash
 193 and
 194 .B tcsh. Nor will it cope with paths containing apostrophes.
 195 It also results in an extra
 196 .B sh
 197 process when the
 198 .B passwd
 199 shell is used. These issues should not be present when invoked via
 200 .B xhere
 201 (
 202 .B -2
 203 ).
 204 .B xhere
 205 requires your login script to check the environment variable
 206 .B CHERE_INVOKING
 207 , and avoid changing to your
 208 .B HOME
 209 directory if it is present. The login script should unset the variable after it sees it, so that subsequent child logins are unaffected.
 210
 211 When using
 212 .B -e
 213 you can specify a keyboard shortcut for the context menu by prefixing the appropriate letter in the text with an ampersand (&).
 214
 215 Freshening (
 216 .B -x
 217 ) updates all currently installed context menu items. However, it does not preserve custom user arguments and menu entry text. If you have previously specified these with
 218 .B -o
 219 or
 220 .B -e,
 221 do not use it.
 222 Freshening does support the use of
 223 .B -o
 224 in the same invocation. It will abort if you attempt to specify the menu text entry with
 225 .B -e.
 226
 227 .SH DEBUGGING
 228 Several options are present to aid debugging.
 229
 230 .PP
 231 The
 232 .B -p
 233 option will print the
 234 .B regtool
 235 commands to
 236 .B stdout
 237 for inspection instead of executing them.
 238
 239 .PP
 240 The
 241 .B -l
 242 command lists the currently installed shell here context menus.
 243
 244 .PP
 245 The
 246 .B -r
 247 command lists the commands currently in the registry associated with all possible context menus.
 248
 249 .PP
 250 The
 251 .B -f
 252 option forces
 253 .B chere
 254 to overwrite existing commands even if
 255 .I shell
 256 can\'t be found
 257
 258 .SH EXAMPLES
 259 .IP
 260 \&./chere -il -t rxvt -s tcsh
 261 .PP
 262 Install
 263 .B tcsh,
 264 for all users using
 265 .B rxvt
 266 as the terminal, then list what is installed.
 267
 268 .SH KNOWN BUGS
 269 If you have an old or custom startup script, the shell may not enter the desired directory. The login script modifications described above are provided in the default startup scripts; the cygwin setup program attempts to merge updates in these scripts to your local login scripts, but this may not work. The default startup scripts can be found at:
 270 .PP
 271 .B /etc/defaults/etc/profile
 272 (provided by base-files, used by
 273 .B ash,
 274 .B bash
 275 and
 276 .B pdksh)
 277 .PP
 278 .B /usr/share/doc/zsh-x.x.x/StartupFiles/zprofile
 279 (provided by zsh)
 280 .PP
 281 .B /usr/share/doc/tcsh/...
 282 (not currently provided)
 283
 284 .SH HINTS
 285 If you are using
 286 .B cmd
 287 as a terminal because you don't want to install
 288 .B X
 289 consider using
 290 .B rxvt
 291 instead.
 292 .PP
 293 If you really do like
 294 .B cmd
 295 you can still use it as a shell in
 296 .B rxvt
 297 or
 298 .B xterm.
 299 .PP
 300 Use
 301 .B ~/.Xdefaults
 302 to set terminal resources (colour, font etc). This even works for rxvt in non-X11 mode.
 303 .PP
 304 You can use
 305 .B -o
 306 to set the terminals -name option,
 307 .B -e
 308 to distinguish the context menu entries, and specify separate terminal resources for each of the context menu entries in
 309 .B ~/.Xdefaults.
 310 .PP
 311 .B http://biocycle.atmos.colostate.edu/~johnk/Xterm-Title.html
 312 has information on setting up Dynamic titles from various shells
 313
 314 .SH ENVIRONMENT
 315 .B CHERE_INVOKING DISPLAY
 316
 317 .SH FILES
 318 .B /etc/passwd /bin/xhere /etc/profile ~/profile ~/.bash_profile ~/.bash_login /etc/csh.login /etc/zprofile $ZDOTDIR/.zprofile /etc/zlogin $ZDOTDIR/.zlogin
 319
 320 .SH AUTHOR
 321 Written by Dave Kilroy <kilroyd@gmail.com>
 322
 323 .SH REPORTING BUGS
 324 Report bugs to <cygwin@cygwin.com>, following the directions in http://cygwin.com/problems.html. Also attach verbatim output of the command
 325 .I chere -r
 326
 327 .SH COPYRIGHT
 328 This script is in the public domain.
 329
 330 .SH SEE ALSO
 331 .B ash bash pdksh tcsh zsh rxvt xterm regtool