Configuration

URL Format

Repo type and address is RFC3986 style URLs. You may recognize this from pip’s VCS URL format.

Config locations

You can place the file in one of three places:

1. Home: ~/.vcspull.yaml

2. XDG home directory: $XDG_CONFIG_HOME/vcspull/

   Example: ~/.config/vcspull/myrepos.yaml

   XDG_CONFIG_HOME is often ~/.config/vcspull/, but can vary on platform, to check:

   $ echo $XDG_CONFIG_HOME
   

3. Anywhere (and trigger via vcspull sync -c ./path/to/file.yaml sync [repo_name])

Schema

Warning

This structure is subject to break in upcoming releases.

~/workdir/:
  repo_name:
    remotes:
      origin: git_repo_url

Examples

Simple

~/workspace/:
  kaptan:
    url: git+https://github.com/emre/kaptan
    remotes:
      upstream: git+https://github.com/emre/kaptan
      marksteve: git+https://github.com/marksteve/kaptan.git
      tony: git+ssh://[email protected]/tony/kaptan.git

To pull kaptan:

$ vcspull sync kaptan

Complex

Christmas tree

config showing off every current feature and inline shortcut available.

~/study/:
    linux: git+git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
    freebsd: git+https://github.com/freebsd/freebsd.git
    sphinx: hg+https://bitbucket.org/birkenfeld/sphinx
    docutils: svn+http://svn.code.sf.net/p/docutils/code/trunk
~/github_projects/:
    kaptan:
        url: git+https://github.com/emre/kaptan
        remotes:
            upstream: git+https://github.com/emre/kaptan
            marksteve: git+https://github.com/marksteve/kaptan.git
            tony: [email protected]:tony/kaptan.git
~:
    .vim:
        url: [email protected]:tony/vim-config.git
    .tmux:
        url: [email protected]:tony/tmux-config.git

Open Source Student

Code scholar

This file is used to checkout and sync multiple open source configs.

YAML:

~/study/c:
  awesome: 'git+git://git.naquadah.org/awesome.git'
  weechat: 'git+git://git.sv.gnu.org/weechat.git'
  retroarch: 'git+https://github.com/Themaister/RetroArch.git'
  linux: 'git+https://github.com/torvalds/linux.git'
  freebsd: 'git+https://github.com/freebsd/freebsd.git'
  ncmpc: 'git+git://git.musicpd.org/master/ncmpc.git'
  tmux: 'git+git://git.code.sf.net/p/tmux/tmux-code'
  git: 'git+https://github.com/git/git.git'
  postgres: 'git+https://github.com/postgres/postgres.git'
  pgadmin3: 'git+git://git.postgresql.org/git/pgadmin3.git'
  sandy: 'git+http://git.suckless.org/sandy'
  understate: 'git+https://github.com/L3V3L9/understate.git'
  util-cursor: 'git+git://anongit.freedesktop.org/xcb/util-cursor'
  zsh: 'git+git://git.code.sf.net/p/zsh/code'
  cpython: 'hg+http://hg.python.org/cpython/'
  vim: 'hg+https://vim.googlecode.com/hg/'
  nginx: 'hg+http://hg.nginx.org/nginx'
~/study/c++:
  vimpc: 'git+https://github.com/boysetsfrog/vimpc'
  mpd: 'git+git://git.musicpd.org/master/mpd.git'
  libmpd: 'git+git://git.musicpd.org/master/libmpd.git'
  ncmpcpp: 'git+git://git.musicpd.org/mirror/ncmpcpp.git'
  libmpdclient: 'git+git://git.musicpd.org/master/libmpdclient.git'
  node: 'git+https://github.com/joyent/node.git'
  libzmp: 'git+https://github.com/zeromq/libzmq.git'
  doubanfm-qt: 'git+https://github.com/zonyitoo/doubanfm-qt.git'
  retroarch-phoenix: 'git+https://github.com/Themaister/RetroArch-Phoenix.git'
  clementine: 'git+https://code.google.com/p/clementine-player/'
  amarok: 'git+git://anongit.kde.org/amarok.git'
~/study/node:
  async: 'git+http://github.com/caolan/async.git'
  request: 'git+git://github.com/mikeal/request.git'
  express: 'git+https://github.com/visionmedia/express.git'
  node-optimist: 'git+http://github.com/substack/node-optimist.git'
  commander.js: 'git+https://github.com/visionmedia/commander.js.git' 
  colors.js: 'git+git://github.com/Marak/colors.js.git'
  uglify.js: 'git+git://github.com/mishoo/UglifyJS.git'
  connect: 'git+git://github.com/senchalabs/connect.git'
  socket.io: 'git+https://github.com/LearnBoost/socket.io.git'
  node-mkdirp: 'git+https://github.com/substack/node-mkdirp.git'
  jade: 'git+https://github.com/visionmedia/jade.git'
  redis: 'git+https://github.com/antirez/redis.git'
  node-uuid: 'git+https://github.com/broofa/node-uuid.git'
  node-mime: 'git+https://github.com/broofa/node-mime.git'
  mime-magic: 'git+https://github.com/SaltwaterC/mime-magic.git'
  debug: 'git+https://github.com/visionmedia/debug.git'
  winston: 'git+https://github.com/flatiron/winston.git'
  less.js: 'git+https://github.com/cloudhead/less.js.git'
  less: 'git+https://github.com/cloudhead/less.git'
  todo: 'git+https://github.com/cloudhead/toto.git'
  http-control: 'git+https://github.com/cloudhead/http-console.git'
  cradle: 'git+https://github.com/cloudhead/cradle.git'
  journey: 'git+https://github.com/cloudhead/journey.git'
  pilgim: 'git+https://github.com/cloudhead/pilgrim.git'
  node-glob: 'git+https://github.com/isaacs/node-glob.git'
  jsdom: 'git+https://github.com/tmpvar/jsdom.git'
  node-mongodb-native: 'git+https://github.com/mongodb/node-mongodb-native.git'
  node-pkginfo: 'git+https://github.com/indexzero/node-pkginfo.git'
  nodejs-intro: 'git+https://github.com/indexzero/nodejs-intro.git'
  wrench-js: 'git+https://github.com/ryanmcgrath/wrench-js.git'
  grunt: 'git+https://github.com/gruntjs/grunt.git'
  moment: 'git+https://github.com/timrwood/moment.git'
  q: 'git+https://github.com/kriskowal/q.git'
  mocha: 'git+https://github.com/visionmedia/mocha.git'
  node-semvar: 'git+https://github.com/isaacs/node-semver.git'
  handlebars.js: 'git+https://github.com/wycats/handlebars.js.git'
  underscore.string: 'git+https://github.com/epeli/underscore.string.git'
  node-oauth: 'git+https://github.com/ciaranj/node-oauth.git'
  vows: 'git+https://github.com/cloudhead/vows.git'
  cheerio: 'git+https://github.com/MatthewMueller/cheerio.git'
  node-mysql: 'git+https://github.com/felixge/node-mysql.git'
  node-querystring: 'git+https://github.com/visionmedia/node-querystring.git'
  node-browserify: 'git+https://github.com/substack/node-browserify.git'
  node-http-proxy: 'git+https://github.com/nodejitsu/node-http-proxy.git'
  through: 'git+https://github.com/dominictarr/through.git'
  superagent: 'git+https://github.com/visionmedia/superagent.git'
  supertest: 'git+https://github.com/visionmedia/supertest.git'
  npm: 'git+https://github.com/isaacs/npm.git'
  passport-oauth: 'git+https://github.com/jaredhanson/passport-oauth.git'
  watch: 'git+https://github.com/mikeal/watch.git'
  hogan.js: 'git+https://github.com/twitter/hogan.js.git'
  mustache: 'git+https://github.com/defunkt/mustache.git'
  node-temp: 'git+https://github.com/bruce/node-temp.git'
  node-sprintf: 'git+https://github.com/maritz/node-sprintf.git'
  nodeunit: 'git+https://github.com/caolan/nodeunit.git'
  cli-color: 'git+git://github.com/medikoo/cli-color.git'
  node-jshint: 'git+https://github.com/jshint/node-jshint.git'
  node-static: 'git+https://github.com/cloudhead/node-static.git'
  passport: 'git+https://github.com/jaredhanson/passport.git'
  shelljs: 'git+https://github.com/arturadib/shelljs.git'
  tutorial-nodejs-cli: 'git+https://github.com/oscmejia/tutorial-nodejs-cli.git'
  cli-table: 'git+https://github.com/LearnBoost/cli-table.git'
  mongoose: 'git+https://github.com/LearnBoost/mongoose.git'
  browserbuild: 'git+https://github.com/LearnBoost/browserbuild.git'
  engine.io: 'git+https://github.com/LearnBoost/engine.io.git'
  engine.io-client: 'git+https://github.com/LearnBoost/engine.io-client.git'
  socket.io: 'git+https://github.com/LearnBoost/socket.io.git'
  socket.io-client: 'git+https://github.com/LearnBoost/socket.io-client.git'
  knox: 'git+https://github.com/LearnBoost/knox.git'
  jsonp: 'git+https://github.com/LearnBoost/jsonp.git'
  node-tar: 'git+https://github.com/isaacs/node-tar.git'
  node-bindings: 'git+https://github.com/TooTallNate/node-bindings.git'
  node-fs-extra: 'git+https://github.com/jprichardson/node-fs-extra.git'
  chai: 'git+https://github.com/chaijs/chai.git'
  grunt-lib-contrib: 'git+https://github.com/gruntjs/grunt-lib-contrib.git'
  node-irc: 'git+https://github.com/martynsmith/node-irc.git'
  jasmine-node: 'git+https://github.com/mhevery/jasmine-node.git'
  node-querystring: 'git+https://github.com/visionmedia/node-querystring.git'
  highlight.js: 'git+https://github.com/isagalaev/highlight.js.git'
~/study/javascript:
  backbone.deepmodel: 'git+https://github.com/powmedia/backbone-deep-model.git'
  underscore: 'git+https://github.com/documentcloud/underscore.git'
  lodash: 'git+https://github.com/bestiejs/lodash.git'
  backbone: 'git+https://github.com/documentcloud/backbone.git'
  requirejs: 'git+https://github.com/jrburke/requirejs.git'
  r.js: 'git+https://github.com/jrburke/r.js.git'
  volo: 'git+https://github.com/volojs/volo.git'
  create-responsive-template: 'git+https://github.com/volojs/create-responsive-template.git'
  yeoman: 'git+https://github.com/yeoman/yeoman.git'
  cajon: 'git+https://github.com/requirejs/cajon.git'
  jquery: 'git+https://github.com/jrburke/jquery.git'
  backbone.marionette: 'git+https://github.com/marionettejs/backbone.marionette.git'
  backbone.wreqr: 'git+https://github.com/marionettejs/backbone.wreqr.git'
  backbone.babysitter: 'git+https://github.com/marionettejs/backbone.babysitter.git'
  flight: 'git+https://github.com/twitter/flight.git'
  bower: 'git+https://github.com/twitter/bower.git'
  codemirror: 'git+https://github.com/marijnh/CodeMirror.git'
  doctorjs: 'git+https://github.com/mozilla/doctorjs.git'
~/study/python:
  jmespath: 'git+https://github.com/boto/jmespath.git'
  anyvcs: 'git+https://github.com/ScottDuckworth/python-anyvcs.git'
  pip: 'git+git://github.com/pypa/pip.git'
  ipdb: 'git+http://github.com/gotcha/ipdb.git'
  virtualenv: 'git+https://github.com/pypa/virtualenv.git'
  jinja2: 'git+https://github.com/mitsuhiko/jinja2.git'
  flask: 'git+https://github.com/mitsuhiko/flask.git'
  flask-script: 'git+https://github.com/techniq/flask-script.git'
  frozen-flask: 'git+https://github.com/SimonSapin/Frozen-Flask.git'
  werkzeug: 'git+https://github.com/mitsuhiko/werkzeug.git'
  logbook: 'git+https://github.com/mitsuhiko/logbook.git'
  cjklib: 'git+https://github.com/cburgmer/cjklib.git'
  pudb: 'git+http://git.tiker.net/trees/pudb.git'
  ipython: 'git+https://github.com/ipython/ipython.git'
  blessing: 'git+https://github.com/erikrose/blessings.git'
  salt: 'git+https://github.com/saltstack/salt.git'
  salt-ui: 'git+https://github.com/saltstack/salt-ui.git'
  salt-formulae: 'git+https://github.com/saltstack/formulae'
  salt-api: 'git+https://github.com/saltstack/salt-api.git'
  salt-cloud: 'git+https://github.com/saltstack/salt-cloud.git'
  salt-vagrant: 'git+https://github.com/saltstack/salty-vagrant.git'
  salt-contrib: 'git+https://github.com/saltstack/salt-contrib.git'
  sqlalchemy: 'git+https://github.com/zzzeek/sqlalchemy.git'
  wtforms: 'git+https://github.com/Khan/wtforms.git'
  botocore: 'git+https://github.com/boto/botocore.git'
  libcloud: 'git+https://github.com/apache/libcloud.git'

  argcomplete: 'git+https://github.com/kislyuk/argcomplete.git'

  lxml: 'git+https://github.com/lxml/lxml.git'

  httpbin: 'git+https://github.com/kennethreitz/httpbin.git'
  envoy: 'git+https://github.com/kennethreitz/envoy.git'
  legit: 'git+https://github.com/kennethreitz/legit.git'
  tablib: 'git+https://github.com/kennethreitz/tablib.git'
  requests: 'git+https://github.com/kennethreitz/requests.git'
  grequests: 'git+https://github.com/kennethreitz/grequests.git'

  kr-sphinx-themes: 'git+https://github.com/kennethreitz/kr-sphinx-themes.git'

  gist-api: 'git+https://github.com/kennethreitz/gistapi.py.git'

  pystache: 'git+https://github.com/defunkt/pystache.git'
  pandas: 'git+https://github.com/pydata/pandas'
  ncmpy: 'git+https://github.com/cykerway/ncmpy.git'

  gevent: 'git+https://github.com/surfly/gevent.git'
  tornado: 'git+https://github.com/facebook/tornado.git'

  soundcloud-cli: 'git+https://github.com/0xPr0xy/soundcloud-cli.git'
  pyradio: 'git+https://github.com/coderholic/pyradio.git'

  sh: 'git+https://github.com/amoffat/sh.git'
  envoy: 'git+https://github.com/kennethreitz/envoy.git'

  glances: 'git+https://github.com/nicolargo/glances.git'
  powerline: 'git+https://github.com/Lokaltog/powerline.git'
  jieba: 'git+https://github.com/fxsjy/jieba.git'
  storm: 'git+https://github.com/emre/storm.git'
  fabric: 'git+https://github.com/fabric/fabric.git'
  ansible: 'git+https://github.com/ansible/ansible'
  fn.py: 'git+https://github.com/kachayev/fn.py.git'
  buildbot: 'git+https://github.com/buildbot/buildbot.git'
  beets: 'git+https://github.com/sampsyo/beets.git'
  magicmethods: 'git+https://github.com/RafeKettler/magicmethods.git'

  gateone: 'git+https://github.com/liftoff/GateOne.git'
  glue: 'git+https://github.com/jorgebastida/glue.git'
  objbrowser: 'git+https://github.com/titusjan/objbrowser'

  pythagora: 'git+https://github.com/tarmack/Pythagora.git'
  youtube-dl: 'git+https://github.com/rg3/youtube-dl.git'
  twisted: 'git+https://github.com/twisted/twisted.git'

  ckan: 'git+https://github.com/okfn/ckan.git'
  hackthebox: 'git+https://github.com/moloch--/RootTheBox.git'
  mediagoblin: 'git+git://gitorious.org/mediagoblin/mediagoblin.git'
  ckan: 'git+https://github.com/okfn/ckan.git'
  reddit: 'git+https://github.com/reddit/reddit.git'

  python_koans: 'git+https://github.com/gregmalcolm/python_koans.git'
  python-guide: 'git+https://github.com/kennethreitz/python-guide.git'
  #introduction_to_sqlalchemy: 'git+https://bitbucket.org/zzzeek/pycon2013_student_package.git'
  probabilistic-programming-and-beyesian-methods: 'git+https://github.com/CamDavidsonPilon/Probabilistic-Programming-and-Bayesian-Methods-for-Hackers.git'
  python-patterns: 'git+https://github.com/faif/python-patterns.git'
  learn-pandas: 'git+https://bitbucket.org/hrojas/learn-pandas.git'

  w3lib: 'git+https://github.com/scrapy/w3lib'
  scrapy: 'git+https://github.com/scrapy/scrapy.git'
  scrapely: 'git+https://github.com/scrapy/scrapely.git'

  calibre: 'git+git://github.com/kovidgoyal/calibre.git'

  kaptan: 'git+https://github.com/emre/kaptan.git'
  aws-cli: 'git+https://github.com/aws/aws-cli.git'

  youcompleteme: 'git+https://github.com/Valloric/YouCompleteMe.git'

  ranger: 'git+git://git.savannah.nongnu.org/ranger.git'

  readthedocs: 'git+https://github.com/rtfd/readthedocs.org.git'
  django: 'git+https://github.com/django/django.git'
  norman: 'hg+https://bitbucket.org/aquavitae/norman/src'
  bpython: 'hg+https://bitbucket.org/bobf/bpython/'
  urwid: 'hg+https://excess.org/hg/urwid/'
  sphinx: 'hg+https://bitbucket.org/birkenfeld/sphinx'
  sphinx-contrib: 'hg+https://bitbucket.org/birkenfeld/sphinx-contrib'
  pexpect-u: 'hg+https://bitbucket.org/takluyver/pexpect'
  pygments: 'hg+http://bitbucket.org/birkenfeld/pygments-main'
  docutils: 'svn+http://svn.code.sf.net/p/docutils/code/trunk'

Worktree configuration

Repositories can declare worktrees—additional checkouts of specific tags, branches, or commits in separate directories. Worktrees are listed under the worktrees key of a repository entry:

# Worktree configuration example
#
# vcspull can manage git worktrees declaratively. Each repository can
# define a list of worktrees under the "worktrees" key. Worktrees
# are checked out in separate directories alongside the main clone.
#
# Each worktree entry requires:
#   dir:     Path for the worktree (relative to workspace root or absolute)
#   Exactly one of:
#     tag:    Tag to checkout (creates detached HEAD)
#     branch: Branch to checkout (updatable via pull)
#     commit: Commit SHA to checkout (creates detached HEAD)
#
# Optional fields:
#   lock:        Lock the worktree to prevent accidental removal
#   lock_reason: Reason for locking (implies lock: true)

~/code/:
  myproject:
    url: "git+https://github.com/myorg/myproject.git"
    worktrees:
      # Pin a stable release for reference
      - dir: "../myproject-v2.0"
        tag: "v2.0.0"
        lock: true
        lock_reason: "production reference"

      # Track a development branch
      - dir: "../myproject-dev"
        branch: "develop"

      # Pin a specific commit for debugging
      - dir: "../myproject-bisect"
        commit: "abc1234"

  another-repo:
    url: "git+https://github.com/myorg/another-repo.git"
    worktrees:
      - dir: "../another-repo-v1.0"
        tag: "v1.0.0"
      - dir: "../another-repo-stable"
        branch: "stable"

Each worktree entry requires:

• dir: Path for the worktree (relative to workspace root or absolute)

• Exactly one of tag, branch, or commit

Optional fields:

• lock: Lock the worktree to prevent accidental removal

• lock_reason: Reason for locking (implies lock: true)

See vcspull worktree for full command documentation.

Caveats

SSH Git URLs

For git remotes using SSH authorization such as git+git@github.com:tony/kaptan.git use git+ssh:

git+ssh://[email protected]/tony/kaptan.git