Git support
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 use-git
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
obvious.
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
cd ~/Documents/MyNiceBooks
git init
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
functionality.
Interplay with other commands
Warning
Only the 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
the --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 update
, addto
, rename
, mv
,
etc. also offer such functionality, and they all go through the --git
flag.
Updating the library
To update the library from a remote repository, you can simply run
papis git pull
Usual workflow
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 --git
or by usingpapis git add
after 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
diff
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.