diff --git a/README.md b/README.md index 391936a..7d3363a 100644 --- a/README.md +++ b/README.md @@ -8,18 +8,29 @@ Flags: - -all=false: don't keep .zip around [prune] - -dir=".": directory to extract the plugins to - -dry=false: dry-run, show what would happen [prune, clean] - -f="": path to list of plugins - -filter=: operate on given plugins only; can be given multiple times - -force=false: force certain actions [prune, clean] - -list-supported-archives=false: list all supported archive types - -ui="oneline": ui mode ('simple' or 'oneline', works with `update` action) + -all + don't keep .zip around [prune] + -dir string + directory to extract the plugins to (default "./pack/vopher/start") + -dry + dry-run, show what would happen [prune, clean] + -f string + path to list of plugins (default "vopher.list") + -filter value + operate on given plugins only; can be given multiple times + -force + force certain actions [prune, clean] + -list-supported-archives + list all supported archive types + -ui update + ui mode ('simple' or 'oneline', works with update action) + -v show version Actions: update - acquires the given plugins from '-f ' + fetch - fetch a remote archive and extract it. the arguments are like fields + in a vopher.list file search - searches http://vimawesome.com/ to list some plugins. Anything after this is considered the query check - checks plugins from '-f ' for newer versions @@ -36,65 +47,66 @@ * no mark means that the plugin is not tracked by vopher sample - prints a sample vopher.list to stdout -## Building / Installation - -To build `vopher`, a working Go compiler is needed. Then do this: - - $> cd /somewhere - $> env GOPATH=`pwd` go get -v github.com/mgumz/vopher - -This will fetch and build `vopher` in the "somewhere/bin" directory. -Copy it to any place you need it. - -To build `vopher` with support for LZMA: - - $> env GOPATH=`pwd` go get -v -tags lzma github.com/mgumz/vopher - -If you've already cloned `vopher` and are rebuilding for tests or contributing, -do the following: - - $> go build - -## The vopher-file format -The vopher-file is pretty simple: +## Sample session - # a comment starts with a '#' - # empty lines are ignored + $> cd ~/.vim - # fetches vim-fugitive, current HEAD - https://github.com/tpope/vim-fugitive +Acquire all of the plugins referenced in 'vopher.list' (the default file) and +put the fetched plugins into the 'pack/vopher/start' folder where Vim8 picks +them up without any further work: - # fetches vim-fugitive, tagged release 'v2.1' - https://github.com/tpope/vim-fugitive#v2.1.zip + $> vopher up + vopher: (10/10) [=================== 100% ====================] - # fetches vim-fugitive, name the output-folder 'foo' - foo https://github.com/tpope/vim-fugitive +So, what's in my 'pack/vopher/start' directory and how do they relate to my +`vopher.list`-file? - # fetches vim-fugitive, apply some options to the - # parser/extractor - https://github.com/tpope/vim-fugitive option1=foo option2=bar + $> vopher status + v EasyDigraph.vim + v buftabs + v goldenview + v unicode.vim + v vim-bbye + v vim-bufferline + v vim-fugitive + v vim-gitgutter + v vim-go + v vim-jinja -## Supported archive types +Lines marked with 'v' are plugins referenced in the `vopher.list`. 'vm' marked +lines are referenced plugins which are missing (acquire them by using the +'update' action). Lines without a special prefix are folders inside the +download folder, but they are not referenced by an entry in `vopher.list`. -* .zip -* .vba and .vba.gz (see [Charles E. Campbell](http://www.drchip.org/astronaut/vim/doc/pi_vimball.txt.html)) -* .tar.gz, .tar.bz2, .tar.bzip2 -* optional: .tar.lzma, .tar.xz +I want to try out a new plugin I found on the internets: + $> vopher fetch https://github.com/idanarye/vim-merginal + vopher: (1/1) [=================== 100% ======================] -## Sample session +Did that work? Lets check: - $> cd ~/.vim + $> vopher status + v EasyDigraph.vim + v buftabs + v goldenview + v unicode.vim + v vim-bbye + v vim-bufferline + v vim-fugitive + v vim-gitgutter + v vim-go + v vim-jinja + vim-merginal -Acquire all of the plugins referenced in 'vopher.list': +Note the lack of 'v' in the last line: `vim-merginal` was an adhoc-fetch which +has no reference in a `vopher.list` and thus *vopher* does not know where this +plugin came from. - $> vopher -f vopher.list -dir bundles up - vopher: (10/10) [=================== 100% ====================] Let's check for updates / new stuff: - $> vopher -f vopher.list -dir bundles -ui simple check + $> vopher check ## goldenview - https://github.com/zhaocai/GoldenView.Vim#V1.3.5 - master commits: @@ -125,31 +137,10 @@ Let's check for updates / new stuff: V1.3.0 2013-04-22T21:57:01Z V1.3.0 ... -`GoldenView.Vim#V1.3.5` is referenced in the vopher.list-file. vopher tries to -guess what commit this actually is and marks that line with a '\*'. so, you can -easily see that there seems to be no new release for 'GoldenView', allthough -there are some new commits. - - -So, what's in my 'bundles' directory and how do they relate to my -vopher.list-file? - - $> vopher -f vopher.list -dir bundles status - v EasyDigraph.vim - buftabs - v goldenview - v unicode.vim - vim-bbye - vim-bufferline - vm vim-fugitive - vim-gitgutter - v vim-go - vim-jinja - -Lines marked with 'v' are plugins referenced in the vopher.list. 'vm' marked -lines are referenced plugins which are missing (acquire them by using the -'update' action). lines without a special prefix are folders inside 'bundles' -but they are not handled by vopher. +`GoldenView.Vim#V1.3.5` is referenced in the `vopher.list`-file. *vopher* +tries to guess what commit this actually is and marks that line with a '\*'. +so, you can easily see that there seems to be no new release for 'GoldenView', +allthough there are some new commits. I need more color! Are there any colorschemes available? @@ -173,39 +164,107 @@ I need more color! Are there any colorschemes available? ... +## Building / Installation + +To build `vopher`, a working Go compiler is needed. Then do this: + + $> mkdir build-vopher && cd build-vopher + $> env GOPATH=`pwd` go get -v github.com/mgumz/vopher + +This will fetch and build `vopher` in the "build-vopher/bin" directory. +Copy the binary to any place you need it. + +To build `vopher` with support for LZMA/XZ: + + $> env GOPATH=`pwd` go get -v -tags lzma github.com/mgumz/vopher + +If you've already cloned `vopher` and are rebuilding for tests or contributing, +do the following: + + $> go build + +## The vopher-file format + +The vopher-file is pretty simple: + + # a comment starts with a '#' + # empty lines are ignored + # whitespaces at start or end of the line are ignored by vopher + + # fetches diffchar from vimscripts + https://vim.sourceforge.io/scripts/download_script.php?src_id=25736 + + # fetches diffchar from vimscripts and pick a proper folder name + diffchar https://vim.sourceforge.io/scripts/download_script.php?src_id=25736 + + # fetches diffchar from vimscripts, pick a proper folder name AND prevent + # stripping away the first path within the .zip file + diffchar https://vim.sourceforge.io/scripts/download_script.php?src_id=25736 strip=0 + + # Github hosts lots of vimscripts and it has special powers: the regular + # file fetching API allows to specifiy versions etc. + + # fetches vim-fugitive, current HEAD + https://github.com/tpope/vim-fugitive + + # fetches vim-fugitive, tagged release 'v2.1' + https://github.com/tpope/vim-fugitive#v2.1.zip + + # fetches vim-fugitive, commit 913fff1cea3aa1a08a360a494fa05555e59147f5 + https://github.com/tpope/vim-fugitive#913fff1cea3aa1a08a360a494fa05555e59147f5 + + # fetches vim-fugitive, commit 913fff1cea3aa1a08a360a494fa05555e59147f5, + # but since it's too long, just use the short-version of it + https://github.com/tpope/vim-fugitive#913fff1c + + # fetches vim-fugitive, apply some options to the + # parser/extractor + https://github.com/tpope/vim-fugitive option1=foo option2=bar + +## Supported archive types + +* .zip +* .vba and .vba.gz (see [Charles E. Campbell](http://www.drchip.org/astronaut/vim/doc/pi_vimball.txt.html)) +* .tar.gz, .tar.bz2, .tar.bzip2 +* optional: .tar.lzma, .tar.xz + +If the archive type can not be guessed by looking at the filename, *vopher* +probes the HTTP server to get a clue about the archive type. + + ## FAQ -> There is no vim-integration!! +> There is no UI integration into *vim*!! Yep, nothing to see on this front here .. yet. I need some means to exchange -messages between vim and vopher in an asyncronous way, without the need for -+clientserver. I am also not so sure that the effort on integrating `vopher` -into the Vim-ui is really worth it: I use `vim` as my text editor, not as a +messages between *vim* and *vopher* in an asyncronous way, without the need for ++clientserver. I am also not so sure that the effort on integrating *vopher* +into the *vim*-UI is really worth it: I use *vim* as my text editor, not as a means to constantly updating and managing the plugins I use. Thus, I consider -using `vopher` a rare case. Using the command line outside of `vim` is fine +using *vopher* a rare case. Using the command line outside of *vim* is fine for me right now. > Why?? -`pathogen` (which is what I use) has no means on it's own to acquire plugins. +*pathogen* (which is what I use) has no means on it's own to acquire plugins. -`vundle` needs `git`. It fetches the whole history of any plugin. I am not +*vundle* needs *git*. It fetches the whole history of any plugin. I am not interested in the history, I am just interested in a certain snapshot for -a certain vim-plugin. In addition to that: the installation of `git` on Windows +a certain vim-plugin. In addition to that: the installation of *git* on Windows takes up ~ 250mb. The sum of my vim-plugins take up ~ 4mb. -*Neobundle* depends on `git` or `svn`. +*Neobundle* depends on *git* or *svn*. > Why not use curl/python/ruby??? -`curl` is easy to install and available everywhere. But it's a bit stupid on -it's own. I would have to write a lot of what `vopher` does on it's own in a +*curl* is easy to install and available everywhere. But it's a bit stupid on +it's own. I would have to write a lot of what *vopher* does on it's own in a real programming language 'x'. Or VimL (vimscript). Which would lead to even more code and maybe an additional interpreter which might need even more stuff. On Windows the curl-binary which supports https weighs ~ 1.6mb. A python installer for Windows weighs ~ 17mb, installed ~ 60mb. Yeah, one could create a standalone binary with something like *PyInstaller*. This does not give -anything substantially better than the `golang`-produced binary and it's builtin +anything substantially better than the *Golang*-produced binary and it's builtin networking and concurrency powers. > But Python and Ruby are just a `brew install` away! @@ -213,10 +272,10 @@ networking and concurrency powers. Yep. If you are working mostly on the same platform you can get very comfortable with your nice and cosy environment. If you switch platform borders on a regular basis, things become a bit more complicated. I want to -place one .zip file on my server, containing all my vim-files, vopher-binaries +place one .zip file on my server, containing all my *vim* files, vopher binaries and then I am ready to go (pun) in no time. -> Will `vopher` handle all the dependencies for me? +> Will *vopher* handle all the dependencies for me? Nope. There is no central repository for plugins which all of the plugin-writers agree on (in contrast, SublimeText3 has the defacto standard @@ -228,5 +287,5 @@ effort and nothing substantial to gain from. ## License -Copyright (c) Mathias Gumz. Distributed under the same terms as Vim itself. +Copyright (c) Mathias Gumz. Distributed under the same terms as *vim* itself. See :help license.