diff options
Diffstat (limited to '.vim/bundle/SudoEdit/doc/SudoEdit.txt')
| -rw-r--r-- | .vim/bundle/SudoEdit/doc/SudoEdit.txt | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/.vim/bundle/SudoEdit/doc/SudoEdit.txt b/.vim/bundle/SudoEdit/doc/SudoEdit.txt new file mode 100644 index 0000000..2e2ff92 --- /dev/null +++ b/.vim/bundle/SudoEdit/doc/SudoEdit.txt @@ -0,0 +1,363 @@ +*SudoEdit.txt* Edit Files using Sudo/su + +Author: Christian Brabandt <cb@256bit.org> +Version: Vers 0.19 Wed, 14 Aug 2013 22:29:27 +0200 +Copyright: (c) 2009-2013 by Christian Brabandt *SudoEdit-copyright* + The VIM LICENSE applies to SudoEdit.vim and SudoEdit.txt + (see |copyright|) except use SudoEdit instead of "Vim". + NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK. + + +============================================================================== +1. Contents *SudoEdit* *SudoEdit-contents* + + 1. Contents......................................: |SudoEdit-contents| + 2. SudoEdit Manual...............................: |SudoEdit-manual| + 1 SudoEdit: SudoRead............................: |SudoRead| + 2 SudoEdit: SudoWrite...........................: |SudoWrite| + 3. SudoEdit Configuration........................: |SudoEdit-config| + 1 SudoEdit on Windows...........................: |SudoEdit-Win| + 4. SudoEdit Debugging............................: |SudoEdit-debug| + 5. SudoEdit F.A.Q................................: |SudoEdit-faq| + 6. SudoEdit History..............................: |SudoEdit-history| + +============================================================================== +2. SudoEdit Manual *SudoEdit-manual* + +Functionality + +This plugin enables vim to read files, using sudo or su or any other tool that +can be used for changing the authentication of a user. Therefore it needs any +of sudo or su installed and usable by the user. This means, you have to know +the credentials to authenticate yourself as somebody else. + +That's why this plugin probably won't work on Windows, but you might be able +to configure it to use a method that works on Windows (see |SudoEdit-config|) + +By default SudoEdit will first try to use sudo and if sudo is not found it +will fall back and try to use su. Note, that you might have to configure these +tools, before they can use them successfully. + +SudoEdit requires at least a Vim Version 7 with patch 111 installed. Patch 111 +introduced the |shellescape()| functionality. On a Mac (using MacVim), it uses +the command "security execute-with-privileges" to query for your password, on +Unix, it can make use of graphical password dialog tools like +ssh-gnome-askpass (see |g:sudo_askpass|) + +The SudoEdit Plugin provides 2 Commands: + +============================================================================== +2.1 SudoRead *SudoRead* + + :SudoRead[!] [file] + +SudoRead will read the given file name using any of the configured methods for +superuser authtication. It basically does something like this: > + + :r !sudo cat file + +If no filename is given, SudoRead will try to reread the current file name. +If the current buffer does not contain any file, it will abort. If the ! +argument is used, the current buffer contents will be discarded, if it was +modified. + +SudoRead provides file completion, so you can use <Tab> on the commandline to +specify the file to read. + +For compatibility with the old sudo.vim Plugin, SudoEdit.vim also supports +reading and writing using the protocol sudo: So instead of using :SudoRead +/etc/fstab you can also use :e sudo:/etc/fstab (which does not provide +filename completion) + +============================================================================== +2.2 SudoWrite *SudoWrite* + + :[range]SudoWrite[!] [file] + +SudoWrite will write the given file using any of the configured methods for +superuser authtication. It basically does something like this: > + + :w !sudo tee >/dev/null file + +If no filename is given, SudoWrite will try to write the current file name. +If the current buffer does not contain any file, it will abort. + +You can specify a range to write just like |:w|. If no range is given, it will +write the whole file. If the bang argument is not given, the buffer will only +be written, if it was modified. + +Again, you can use the protocol handler sudo: for writing. + +============================================================================== +3. SudoEdit Configuration *SudoEdit-config* + +By default SudoEdit will try to use sudo and if it is not found, it will try +to use su. Just because SudoEdit finds either sudo or su installed, does not +mean, that you can already use it. You might have to configure it and of +course you need to have the credentials for super-user access. + + *g:sudoAuth* + +The tool to use for authentication is can be changed by setting the variable +g:sudoAuth. If this variable exists, SudoEdit will first try to use the +specified tool before falling back to either sudo or su (in that order). + +For example, you could use ssh to use as authentication tool by setting +g:sudoAuth in your .vimrc as follows: > + + let g:sudoAuth="ssh" +< + *g:sudoAuthArg* + +The variable g:sudoAuthArg specifies how to use the given authentication tool. +You can specify additional parameters that will be used. You could for example +also define here which user to change to. By default, SudoEdit will try to +become the superuser e.g. root. + +If you want to use ssh as authentication facility, you can set g:sudoAuthArg +as follows in your .vimrc: > + + let g:sudoAuthArg="root@localhost" + +For su, you would use g:sudoAuthArg="-c", but you do not have to set it, the +plugin will automatically use -c if it detects, that su is used. + + *g:sudo_no_gui* *g:sudo_askpass* + +If the plugin uses sudo for authenticating and the plugin finds any of +gnome-ssh-askpass, ksshaskpass or x11-ssh-askpass and a graphical Display +connection is possible, the plugin uses the first of the tools it finds to +display a graphical dialog, in which you can enter the password. If you like +to specify a different tool, you can set the g:sudo_askpass variable to +specify a different tool to use, e.g. > + + :let g:sudo_askpass='/usr/lib/openssh/gnome-ssh-askpass' + +to make use of gnome-ssh-askpass for querying the password. + +If you like to disable this, set the variable g:sudo_no_gui, e.g. > + + :let g:sudo_no_gui=1 + +============================================================================== +3.1 SudoEdit on Windows *SudoEdit-Win* + +It should be possible to use SudoEdit on Windows using the runas command. The +plugin should by default try to detect when it runs under Windows and either +try to use runas or elevate. For this to work, those commands need to be in +your %PATH% and be executable. For runas, SudoEdit tries to simply run the +command like this: > + + runas /noprofile /user:Administrator "type file" + +while elevate would simply use: > + + elevate "type file" + +This has not yet been tested, but if you have successfully setup SudoEdit on +Windows, please let me know, so that the procedure can be properly documented. + +Alternatively, it should be possible to setup SudoEdit to use the ShellRunAs, +sudowin or the Surun command and configuring the plugin using the |g:sudoAuth| +and |g:sudoAuthArg| variables. + +If you need to use a different administrator account for Windows, I suggest +that you set the |g:sudoAuthArg| variable, e.g. setting: > + + :let g:sudoAuthArg = '/noprofile /user:\"AdminUser@MyDomain\"' + +to let SudoEdit use the AdminUser within the domain MyDomain for administrator +access. + +For further help on this topic see those links: + +runas: +http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/runas.mspx + +sudowin: +http://sourceforge.net/projects/sudowin/ + +elevate: +http://technet.microsoft.com/en-us/magazine/2007.06.utilityspotlight.aspx + +ShellRunAs: +http://technet.microsoft.com/en-us/sysinternals/cc300361.aspx + +Surun: +http://kay-bruns.de/wp/software/surun/ + +Alternatively, on recent Windows versions, you can use the builtin UAC system +and have a batch script automatically elevated, which will do the writing and +reading of the file. This method is rather experimental and might not work in +all cases. To make use of UAC set the g:sudoAuth variable to the string "uac": +> + + :let g:sudoAuth="uac" + +============================================================================== +4. SudoEdit Debugging *SudoEdit-debug* + +You can debug this plugin and the shell code that will be executed by +setting: > + + let g:sudoDebug=1 + +This ensures, that debug messages will be appended to the |message-history|. + +============================================================================== +5. SudoEdit F.A.Q. *SudoEdit-faq* + +1) This plugin isn't working, while executing the same commands on the + shell works fine using sudo. + +Make sure, that requiretty is not set. If it is set, you won't be able to use +sudo from within vim. + +2) Vim is frozen! + +Vim is probably waiting for the password but not redrawing correctly. You +should be able to enter your passphrase followed by Enter blindly and Vim +should respond again. In this case, try, if setting the g:sudoDebug variable +in your .vimrc helps > + + :let g:sudoDebug = 1 + +That should make the plugin output some more information and you should be +able to see the password prompt. + +3) The plugin is still not working! + +Write me an email (look in the first line for my mail address), append the +debug messages and tell me what exactly is not working. I will look into it +and if there is a bug fix this plugin. + +4) The plugin does not create undo-files. What's wrong? + +It is not directly possible to create undofiles in write-protected +directories, therefore, when your 'undodir' setting contains '.' (the +default), the plugin won't simply write the undofile. If you want undofiles to +work, set the 'undodir' option to a directory, that is writable. + +5) Great work! + +Write me an email (look in the first line for my mail address). And if you are +really happy, vote for the plugin and consider looking at my Amazon whishlist: +http://www.amazon.de/wishlist/2BKAHE8J7Z6UW + +6) Plugin Feedback *SudoEdit-feedback* + +Feedback is always welcome. If you like the plugin, please rate it at the +vim-page: +http://www.vim.org/scripts/script.php?script_id=2709 + +You can also follow the development of the plugin at github: +http://github.com/chrisbra/SudoEdit.vim + +Please don't hesitate to report any bugs to the maintainer, mentioned in the +third line of this document. + +============================================================================== +6. SudoEdit History *SudoEdit-history* + 0.19: Aug 14, 2013 "{{{1 + - |SudoWrite| should always write if a filename has been given + (issue #23, reported by Daniel Hahler, thanks!) + - Better filename completion for |SudoWrite| and |SudoRead| + commands (issue #20 reported by Daniel Hahler, thanks!) + - Fix error in VimLeave autocommand (issue #22, reported by Daniel + Hahler, thanks!) + - reset 'shell' value (issue #24, reported by Raghavendra Prabhu, + thanks!) + 0.18: Feb 16, 2013 "{{{1 + - expand() may return empty filenames (issue #17 + patch by Daniel Hahler, thanks!) + - better exception handling (issue #19) + - included sudo.cmd for better usage on Windows + - enable sudo.cmd to use UAC optionally + 0.17: Aug 20, 2012 "{{{1 + - Guard against a vim without persistent_undo feature + - fix variable typo + (https://github.com/chrisbra/SudoEdit.vim/pull/16 + patch by NagatoPain, thanks!) + 0.16: May 17, 2012 "{{{1 + - Make the plugin usable on Windows |SudoEdit-Win| + 0.15: May 08, 2012 "{{{1 + - fix Syntax error (reported by Gary Johnson, thanks!) + 0.14: Apr 30, 2012 "{{{1 + - fix issue #15 + (https://github.com/chrisbra/SudoEdit.vim/issues/15 + reported by Lenin Lee, thanks!) + 0.13: Apr 28, 2012 "{{{1 + - in graphical Vim, display messages, so one knows, that one needs + to enter the password (reported by Rob Shinn, thanks!) + - Allow bang attribute to |SudoRead| and |SudoWrite| + - Make use of graphical dialogs for sudo to read the passwords, if + possible + - Better debugging + - Code cleanup + - better filename completion with :SudoRead/SudoWrite (now also + supports completing sudo: protocol handler) + 0.12: Jan 31, 2012 "{{{1 + - Avoid redraw when changing permissions of the undofile + - Don't move cursor on Reading/Writing + (issue https://github.com/chrisbra/SudoEdit.vim/issues/11, + reported by Daniel Hahler, Thanks!) + - Support for calling Netrw with another userid/password + (issue https://github.com/chrisbra/SudoEdit.vim/issues/4, + reported by Daniel Hahler, Thanks!) + - Autocmds for Writing did not fire (issue + https://github.com/chrisbra/SudoEdit.vim/issues/10, partly by + Raghavendra D Prabhu, Thanks!) + - Newly created files are not set 'nomodified' (issue + https://github.com/chrisbra/SudoEdit.vim/issues/12, reported by + Daniel Hahler, Thanks!) + - Can't create undofiles in write-protected directories (issue + https://github.com/chrisbra/SudoEdit.vim/issues/14, reported by + Matias Kangasjärvelä, Thanks!) + 0.11: Dec 15, 2011 "{{{1 + -change owner of undofile to that of the edited super-user file, + so vim will automatically load the undofile when opening that + file the next time (reported by Sean Farley and blueyed, thanks!) + -Only set the filename using :f when writing to another file + (https://github.com/chrisbra/SudoEdit.vim/pull/8 and also + https://github.com/chrisbra/SudoEdit.vim/issues/5 patch by + Daniel Hahler, thanks!) + -fix https://github.com/chrisbra/SudoEdit.vim/issues/6 + (fix permissions and path of the undofile, partly by Daniel + Hahler, thanks!) + -Don't reread the file and write undofiles for empty files + (https://github.com/chrisbra/SudoEdit.vim/issues/7 reported by + Daniel Hahler, thanks!) + 0.10: Nov 18, 2011 "{{{1 + -fix https://github.com/chrisbra/SudoEdit.vim/issues/1 + (exception "emptyfile" not caught, reported by Daniel Hahler, + thanks!) + -fix https://github.com/chrisbra/SudoEdit.vim/issues/2 + (Avoid W13 error, reported by Daniel Hahler, thanks!) + -fix https://github.com/chrisbra/SudoEdit.vim/issues/3 + (Write undofiles, reported by Daniel Hahler, thanks!) + 0.8: Apr 20, 2010 "{{{1 + - Made plugin autoloadable so the code is only loaded, + when necessary + 0.7: Oct 26, 2009 "{{{1 + - Support for reading/writing using sudo: protocol handler + - Added Debugging capabilities + 0.6: July 14, 2009 "{{{1 + - Fix minor bug, that prevents setting the filename correctly + when writing. + 0.5: July 08, 2009 "{{{1 + - Enables the plugin for |GetLatestVimScripts| + 0.4: July 08, 2009 "{{{1 + - First release + - Added Documentation + 0.3: July 07, 2009 "{{{1 + - Internal version, added su support + - Added configuration variables + 0.2: July 07, 2009 "{{{1 + - Internal version, Working sudo support + - Created plugin + 0.1: July 07, 2009 "{{{1 + - Internal version, First working version, using simple commands + +============================================================================== +Modeline: "{{{1 +vim:tw=78:ts=8:ft=help:fdm=marker:fdl=0:norl |