Can I make a suggestion for improving documentation - inconsistent state error messages

[plastikfan]

I'm just getting started with chezmoi and having been a user of git/github for many years, I have had some serious teething problems with chezmoi. The documentation of chezmoi is very good however, I have spotted some glaring omissions I would suggest be fixed.

The number one point that users need to realise, especially if they are git experts, is for most if not all write operations to git, you should ALWAYS use the chezmoi git equivalent, not doing so will make you get inconsistent state error messages that you will probably only be able to fix if you already know how chezmoi works. This is not spelled out clearly enough in getting started or trouble shooting sections.

I have noticed that sometimes, the documentation just makes assumptions, sometimes wrong, so that if you follow what is documented, you don't get the result you expected or your setup gets into an erroneous state.

I'm not sure what correct course of action I should take to get some of these points addressed, but opening a discussion seemed to me the best way to do this.

Apart from the teething problems I have experienced, I am so glad that I discovered this project as it is a powerhouse of awesomeness that with persistence and determination I hope to be able to build up a maintainable and portable config, so I thank all contributors for their work and of course twpayne.

[halostatue]

The number one point that users need to realise, especially if they are git experts, is for most if not all write operations to git, you should ALWAYS use the chezmoi git equivalent, not doing so will make you get inconsistent state error messages that you will probably only be able to fix if you already know how chezmoi works. This is not spelled out clearly enough in getting started or trouble shooting sections.

I'm not sure what you mean here. I never use the chezmoi git commands, so I don't know what issues you might be referring to.

Documentation errors are bugs that should be reported. Since you've started a discussion, I would suggest that you start with being more specific about what errors you believe you found on which pages. If they are real bugs (mistakes in the documentation) we will get them fixed; if they are instead sources of misunderstanding, we can look at trying to clarify them.