Papis is made to work well with git and has
functionality in most of its command to interact with it. This functionality
can be turned on by default by using the
configuration setting. This guide gives a description of a possible workflow
for using Git with Papis. This is not the only workflow, but it is the most
Let’s say you have a library named
books in the directory
~/Documents/MyNiceBooks. You could turn the
books library into
a Git repository by running
papis -l books git init
which is completely equivalent to going into the library directory and running the commands there
As this is the first run, we can just add all the documents to the repository
(equivalent to a
git add . and a
git commit -m '...')
papis -l books git add .
papis -l books git commit -m 'initial commit'
In general the
papis git command will just forward any arguments directly
to the underlying
git command. This allows users to easily access any Git
Interplay with other commands
papis git command can be used to initialize a Git repository.
All other commands assume the repository exists in the directory of the
current library and their Git functionality will fail otherwise.
Some papis commands give you the opportunity of using Git to manage
changes. For instance, if you are adding a new document, you could use
--git flag to also commit the document into Git like this
papis add --git --set author 'Pedrito' --set title 'Super book' book.pdf
In this case, Papis will do an automatic add + commit for the document. After that, you can push your library to a remote repository by running
papis git push origin main
As expected, other Papis commands like
etc. also offer such functionality, and they all go through the
Updating the library
To update the library from a remote repository, you can simply run
papis git pull
With all this in mind, assuming the you have a
git repository set up in
the library folder, a
papis git workflow could be based on the following.
When adding a document that you know for sure you want in your library:
Add the document and commit it, either by
papis add --gitor by using
papis git addafter adding it to the library.
Pull changes from the remote repository, maybe you pushed something on another machine (reference changes, etc.) and you do not have it on you current machine. You would do something like
papis git pull
Push what you just added
papis git push
Review the status of the library
papis git status
When editing a document’s info file:
Edit the file and then take a look at the
papis git diff
Add the changes to the staging area
papis git add --all
Commit the changes
papis git commit
Push your changes.
Of course these workflows are just very basic examples. Your optimal workflow could look completely different.