From eb7ee0ef6c9d46c45f33a92d8995ca89850e82af Mon Sep 17 00:00:00 2001 From: Jethro Kuan Date: Sun, 19 Jul 2020 12:37:53 +0800 Subject: [PATCH] (docs): add docs on notes versioning (#949) --- doc/org-roam.org | 21 ++++++++++++++++----- doc/org-roam.texi | 31 ++++++++++++++++++++++--------- 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/doc/org-roam.org b/doc/org-roam.org index fde3644..6535004 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -851,7 +851,9 @@ org-roam-doctor~, but note that this may take some time. Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run the check only for the current buffer. -The checks run are defined in ~org-roam-doctor--checkers~. Each checker is an instance of ~org-roam-doctor-checker~. To define a checker, use ~make-org-roam-doctor-checker~. Here is a sample definition: +The checks run are defined in ~org-roam-doctor--checkers~. Each checker is an +instance of ~org-roam-doctor-checker~. To define a checker, use +~make-org-roam-doctor-checker~. Here is a sample definition: #+BEGIN_SRC emacs-lisp (make-org-roam-doctor-checker @@ -920,7 +922,6 @@ General Public License for more details. - Videos :: - [[https://www.youtube.com/watch?v=RvWic15iXjk][How to Use Roam to Outline a New Article in Under 20 Minutes]] ** Ecosystem -A number of packages work well combined with Org-Roam: *** Browsing History with winner-mode @@ -934,13 +935,23 @@ A number of packages work well combined with Org-Roam: (define-key winner-mode-map (kbd "") #'winner-redo) #+END_SRC -*** Deft +*** Versioning Notes + +Since Org-roam notes are just plain text, it is trivial to track changes in your +notes database using version control systems such as [[https://git-scm.com/][Git]]. Simply initialize +~org-roam-directory~ as a Git repository, and commit your files at regular or +appropriate intervals. [[https://magit.vc/][Magit]] is a great interface to Git within Emacs. + +In addition, it may be useful to observe how a particular note has evolved, by +looking at the file history. [[https://gitlab.com/pidu/git-timemachine][Git-timemachine]] allows you to visit historic +versions of a tracked Org-roam note. + +*** Full-text search interface with Deft :PROPERTIES: :CUSTOM_ID: deft :END: -[[https://jblevins.org/projects/deft/][Deft]] provides a nice interface -for browsing and filtering org-roam notes. +[[https://jblevins.org/projects/deft/][Deft]] provides a nice interface for browsing and filtering org-roam notes. #+BEGIN_SRC emacs-lisp (use-package deft diff --git a/doc/org-roam.texi b/doc/org-roam.texi index f065652..e7e7653 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -138,7 +138,8 @@ Appendix Ecosystem * Browsing History with winner-mode:: -* Deft:: +* Versioning Notes:: +* Full-text search interface with Deft:: * Org-journal:: * Note-taking Add-ons:: @@ -1155,7 +1156,9 @@ Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run the check only for the current buffer. @end itemize -The checks run are defined in @code{org-roam-doctor--checkers}. Each checker is an instance of @code{org-roam-doctor-checker}. To define a checker, use @code{make-org-roam-doctor-checker}. Here is a sample definition: +The checks run are defined in @code{org-roam-doctor--checkers}. Each checker is an +instance of @code{org-roam-doctor-checker}. To define a checker, use +@code{make-org-roam-doctor-checker}. Here is a sample definition: @lisp (make-org-roam-doctor-checker @@ -1246,11 +1249,10 @@ operations. To reduce the number of garbage collection processes, one may set @node Ecosystem @section Ecosystem -A number of packages work well combined with Org-Roam: - @menu * Browsing History with winner-mode:: -* Deft:: +* Versioning Notes:: +* Full-text search interface with Deft:: * Org-journal:: * Note-taking Add-ons:: @end menu @@ -1269,11 +1271,22 @@ A number of packages work well combined with Org-Roam: @end lisp -@node Deft -@subsection Deft +@node Versioning Notes +@subsection Versioning Notes -@uref{https://jblevins.org/projects/deft/, Deft} provides a nice interface -for browsing and filtering org-roam notes. +Since Org-roam notes are just plain text, it is trivial to track changes in your +notes database using version control systems such as @uref{https://git-scm.com/, Git}. Simply initialize +@code{org-roam-directory} as a Git repository, and commit your files at regular or +appropriate intervals. @uref{https://magit.vc/, Magit} is a great interface to Git within Emacs. + +In addition, it may be useful to observe how a particular note has evolved, by +looking at the file history. @uref{https://gitlab.com/pidu/git-timemachine, Git-timemachine} allows you to visit historic +versions of a tracked Org-roam note. + +@node Full-text search interface with Deft +@subsection Full-text search interface with Deft + +@uref{https://jblevins.org/projects/deft/, Deft} provides a nice interface for browsing and filtering org-roam notes. @lisp (use-package deft