README

*SudoEdit.txt*  Edit Files using Sudo/su

Author:  Christian Brabandt <cb@256bit.org>
Version: Vers 0.21 Thu, 15 Jan 2015 20:57:15 +0100
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 authentication. 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 command line 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 authentication. 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
<
							      *g:sudo_tee*

By default, the SudoEdit plugin uses the tee command to write your file (at
least on Unix and Mac). If you don't have the tee command available in your
path or you want to use a different tool, that is similar but called
differently, specify this option like this: >

    :let g:sudo_tee='/usr/bin/tee'

==============================================================================
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"

Technically, this works, by calling a VBScript, that will create a UAC dialog
and on success write the files. This script is called GetPrivileges.vbs and is
distributed with SudoEdit.vim plugin and lives within the autoload folder
where the SudoEdit plugin resides.
==============================================================================
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) Plugin doesn't work in neovim, how to make it to work?

Yeah, it is a known problem that neovim broke compatibility here. Since I am not using Neovim, I am not able to fix it.

Alternatively you can set the the ask pass to be GUI which should work.
Remember to install the 'gnome-ssh-askpass':

      :let g:sudo_askpass='/usr/lib/openssh/gnome-ssh-askpass'

Alternatively you can use the following "fork-ish" plugin that supports neovim
https://github.com/lambdalisue/suda.vim

6) 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 wish list:
http://www.amazon.de/wishlist/2BKAHE8J7Z6UW

7) 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.21: Jan 15, 2015 "{{{1
	    - temporarily set shelltemp (issue
	      https://github.com/chrisbra/SudoEdit.vim/issues/32, reported by
	      Fernando da Silva, thanks!)
	    - Do not trigger autocommands when writing temp files
	    - Make UAC actually work for Windows
	    - many small improvements for Windows
	    - do not call expand() for $SHELL variables (issue
	      https://github.com/chrisbra/SudoEdit.vim/pull/34, fixed by
	      Daniel Hahler, thanks!)
	    - remove writable file always (and make sure it will be different
	      in case of the Vim running twice).
	    - Reset 'shellslash' on windows (suggested by Boris Danilov,
	      thanks!)
	    - change redirection when calling UAC vbs script (suggested by
	      Boris Danilov, thanks!)
	    - distribute the UAC VBScript together with the SudoEdit plugin
	    - fix spelling mistakes (issue
	      https://github.com/chrisbra/SudoEdit.vim/pull/35, fixed by
	      Tim Sæterøy, thanks!)
	    - Check file modification time before asking for reloading buffers
	0.20: Mar 27, 2014 "{{{1
	    - skip writing undo, if the buffer hasn't been written.
	    - document |g:sudo_tee| variable
	    - possibly wrong undofile was written (issue
	      https://github.com/chrisbra/SudoEdit.vim/issues/21, reported by
	      blueyed, thanks!)
        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