documentation: .gitattributes and .git/config - install still required after cloning

consideRatio commented 5 years ago

I thought writing to .gitattributes would make someone cloning the repo to get the nbstripout functionality out of the box assuming nbstripout and a .gitattributes file was provided in the repo. But, after thorough inspection I realized that the .gitattributes file only references a name (nbstripout / ipynb) that needs to be defined somewhere.

.gitattributes (in repo) or .git/info/attributes (local)

*.ipynb filter=nbstripout
*.ipynb diff=ipynb

The git configuration with the actual definitions of referenced functionality (nbstripout / ipynb) can either in the local .git/config or system wide in /etc/gitconfig.

.git/config (local), ~/.gitconfig (global), or /etc/gitconfig (system)

[filter "nbstripout"]
        clean = \"/opt/conda/bin/python3.6\" \"/opt/conda/lib/python3.6/site-packages/nbstripout\"
        smudge = cat
        required = true
[diff "ipynb"]
        textconv = \"/opt/conda/bin/python3.6\" \"/opt/conda/lib/python3.6/site-packages/nbstripout\" -t

Learning this, I realized that someone cloning the repo would also need to run nbstripout --install unless they were provided with a system wide git configuration with these definitions.

It would be useful to have this understanding communicated in the repo! Thanks for providing that excellent video earlier btw, that was great!

kynan commented 5 years ago

This is now documented. Can we close this?

consideRatio commented 5 years ago

Thank you @kynan ! Excellent work on this!

dkipping commented 4 years ago

@kynan Hi, thanks for this great tool and the nice documentation!

When I follow the referenced global installation like this: nbstripout --install --global --attributes=~/.config/git/attributes

...before cloning a git repository and being in it, I am running into the following error:

fatal: not a git repository (or any of the parent directories): .git
Installation failed: not a git repository!

Is this design intentional? Like this I could not set up a global git filter without already being within a git repository. I would guess either the global or the attributes flag are ignored here, resulting in a failing trial of installation of the filters into a repository specific file.

kynan commented 4 years ago

No, that is not intentional. Can you open a new bug for this @dkipping ?

kynan / nbstripout

documentation: .gitattributes and .git/config - install still required after cloning #100