Confusion about what `path` actually represents

[gtirloni]

My goal is to synchronize a few Git repositories in a certain local directory.

It seems path can be a completely different object if it's under directories or contents. Here's my journey.

One cannot specify . as the directory and add entries in contents:

$ cat vendir.yml 
apiVersion: vendir.k14s.io/v1alpha1
kind: Config

directories:
  - path: '.'
    contents:
      - path: examples
        git:
          url: https://github.com/kubernetes/examples
          ref: master

$ vendir sync
vendir: Error: Parsing resource config 'vendir.yml':
  Unmarshaling config:
    Validating config:
      Validating directory '.' (0):
        Expected path to not be one of '/', '.', '..', ''

And it's also not possible to specify a list of directories directly under directories:

$ cat vendir.yml 
apiVersion: vendir.k14s.io/v1alpha1
kind: Config

directories:
  - path: examples
    git:
      url: https://github.com/kubernetes/examples
      ref: master

$ vendir sync
Lock config

apiVersion: vendir.k14s.io/v1alpha1
directories:
- contents: null
  path: examples
kind: LockConfig

Succeeded

$ ls -l examples/
total 0

Even with contents it doesn't work:

$ cat vendir.yml 
apiVersion: vendir.k14s.io/v1alpha1
kind: Config

directories:
  - path: examples
    contents:
      git:
        url: https://github.com/kubernetes/examples
        ref: master

$ vendir sync
vendir: Error: Parsing resource config 'vendir.yml':
  Unmarshaling config:
    Unmarshaling config: error unmarshaling JSON: while decoding JSON: json: cannot unmarshal object into Go struct field Directory.directories.contents of type []config.DirectoryContents

The Eureka moment: path is not the same kind of object with everywhere.

Finally, the workaround solution is to define another self-referencing . path. Now, this works:

$ cat vendir.yml 
apiVersion: vendir.k14s.io/v1alpha1
kind: Config

directories:
  - path: examples
    contents:
      - path: .
        git:
          url: https://github.com/kubernetes/examples
          ref: master

$ vendir sync
Fetching: examples + . (git from https://github.com/kubernetes/examples@master)

  --> git init
  [...]

Lock config

apiVersion: vendir.k14s.io/v1alpha1
directories:
- contents:
  - git:
      commitTitle: 'Merge pull request #497 from humblec/glusterfs-deprecation...'
      sha: fb9ac11f42d665ae47cddbaea15c1f112c5f0464
    path: .
  path: examples
kind: LockConfig

Succeeded

A few thoughts:

• Maybe contents should actually be subdirectories, but still subdirectories would have a different schema from directories (confusing)
• Documentation could be changed to somehow mention that directories is just a local structure used to store contents and that a content is the actual thing you want to synchronize. I assume most people will be familiar with rsync and how it synchronizes remote directories with local directories but that's not how vendir works.

[praveenrewar]

Hi @gtirloni! Do you think the vendir spec is helpful in understanding that the directories is just the directories that we want to manage using vendir? I guess the contents part is something that we could enhance? (Moving the issue to the https://github.com/carvel-dev/carvel repo as it's a docs issue Nevermind, can't do it from my phone)

[gtirloni]

IMHO, the spec is fine. I wanted to tell my story just to show that someone could be confused by prior rsync-like knowledge. Maybe just docs update would be fine. Thanks for creating this tool, very useful.