Lock command removes comments from configuration file

[daniel-brosche]

A given gitman.yml like:

location: demo
sources:
# gitman sources part 1
- name: gitman_1
  repo: https://github.com/jacebrowning/gitman-demo
  rev: example-branch

# --------------------------------------------------- 
# Here some more documentation about the dependencies
# ---------------------------------------------------

# gitman sources part 2
- name: gitman_2
  repo: https://github.com/jacebrowning/gitman-demo
  rev: example-tag

will be transformed after a lock operation to:

location: demo
sources:
- name: gitman_1
  type: git
  repo: https://github.com/jacebrowning/gitman-demo
  sparse_paths:
  -
  rev: example-branch
  link:
  scripts:
  -
- name: gitman_2
  type: git
  repo: https://github.com/jacebrowning/gitman-demo
  sparse_paths:
  -
  rev: example-tag
  link:
  scripts:
  -
sources_locked:
- name: gitman_1
  type: git
  repo: https://github.com/jacebrowning/gitman-demo
  sparse_paths:
  -
  rev: 1de84ca1d315f81b035cd7b0ecf87ca2025cdacd
  link:
  scripts:
  -
- name: gitman_2
  type: git
  repo: https://github.com/jacebrowning/gitman-demo
  sparse_paths:
  -
  rev: 7bd138fe7359561a8c2ff9d195dff238794ccc04
  link:
  scripts:
  -

Unfortunately, most importantly the comments are removed and secondly the structure of the gitman.yml will be changed. In this matter, all available but unused parameters for an source entry will be added.

I see the benefit to keep the comments and also not to spoil the gitman.yml with unused settings (at least for the sources section. Maybe it is an approach to seperate the source_locked section in a seperate file.

[jacebrowning]

What are your use cases for comments?

[daniel-brosche]

The basic use case is that I have a gitman.yml with a bunch of source dependencies. A couple of them can be logicaly grouped and this group information (why this imports are needed, which imports are closely related, which should be updated together) has been documented directly inside of the gitman.yml. Because of comments are an integral part of yml file format it would be nice if this can be used to document the gitman.yml contents.

[jacebrowning]

This would require using a different YAML library (https://stackoverflow.com/a/27103244/429533) in the upstream YAML library. I might consier this down the road, but this would be a pretty major change.

We could add a description and/or comment field. I think I'd like to wait for more people to ask for this.

In this matter, all available but unused parameters for an source entry will be added.

I would eventually like to address this in the upstream YAML library.

[daniel-brosche]

I do understand the impact. Maybe another solution is not to modify the gitman.yml and store the sources_locked section in a seperate file. I think it is possible to add this as a seperate feature. One possible solution could be to add a new optional argument to pass a filepath or just an option to instruct that source_locked will be stored in a file by convention like gitman.lock.yml. Over this way the commands lock and install could store and load the content from a seperate file and leaf the main gitman.yml untouched. As a result the main gitman.yml will not be rewritten by this operations so that the comments and the overall structure will be preserved.

An extension of this could be to use the untouched gitman.yml as a template and just replace the rev values so that the same layout will be used for the gitman.lock.yml file. But in my case the most important thing is to preserve the main gitman.yml file.

Just some ideas...

[jacebrowning]

I agree that this would be nicer and if I were building this again today, I think I would have opted for a separate lock file.

Let's consider this a feature request for 2.0. 😄

[daniel-brosche]

Could we tag this to group feature request for gitman 2.0?

[jacebrowning]

I'm working on rewriting the underlying YAML library with the intention of being able to preserve comments: https://github.com/jacebrowning/datafiles

[jacebrowning]

YORM has been replaced with datafiles in the 2.0 beta releases, but we're not yet able to attach comments to list items: https://github.com/jacebrowning/datafiles/issues/171