manafiles/README.org

#+TITLE: Manafiles
#+AUTHOR: Riyyi
#+LANGUAGE: en
#+OPTIONS: toc:nil

Config file and package tracking utility.

- Manage dotfiles and system config files.
- Selectively comment and uncomment depending on machine configuration.
- Store a list of all installed packages.
- Install packages from a stored list.

** Getting started

*** Installation

If you are using *Arch Linux*, you can install the AUR package [[https://aur.archlinux.org/packages/manafiles-git/][manafiles-git]].

Alternatively, you will have to [[#compiling][build from source]].

*** Configuration

**** Install the example configuration

During installation, manafiles will install the example config to: \\
~/usr/share/doc/manafiles/examples/manafiles.json~

From there you can copy it to anywhere in the working directory,
the config file is searched recursively. \\
~$HOME/<dotfiles>/<anywhere>~

**** Ignore patterns

Everything in this list will get ignored when pulling/pushing config files from the working directory. \\
Currently two types of file matching are supported:

- ~literal~ matches a file or directory literally
- ~wildcard~ the asterisk matches zero or more characters

These behave similarly to a ~.gitignore~ pattern.

- If the pattern starts with a slash, it matches files and directories in the working directory root only.
- If the pattern doesn’t start with a slash, it matches files and directories in any directory or subdirectory.
- If the pattern ends with a slash, it matches only directories. When a directory is ignored, \\
  all of its files and subdirectories are also ignored.

The ignore patterns from the example config:
#+BEGIN_SRC javascript
"ignorePatterns" : [
	".git/",
	"*.md",
	"manafiles.json",
	"packages",
	"README.org",
	"screenshot.png"
]
#+END_SRC

**** System config files

Everything in this list will be pushed to the root ~/~ of the system, instead of ~$HOME~. \\
These support the same file matching as explained in the [[#ignore-patterns][Ignore patterns]] section.

The system patterns from the example config:
#+BEGIN_SRC javascript
"systemPatterns": [
	"/boot/",
	"/etc/",
	"/usr/lib/",
	"/usr/share/"
]
#+END_SRC

*** Usage

**** Selectively comment and uncomment

Config files can be pushed from the working directory to the system like so:

#+BEGIN_SRC shell-script
$ manafiles -Fs
#+END_SRC

When pushing files to the system, manafiles recognizes special blocks and comments
or uncomments them depending on the machine's configuration. Such a block looks
like this:

#+BEGIN_SRC shell-script
# >>> distro=arch hostname=arch-desktop user=anon
export PATH="$PATH:$HOME/.local/bin"
# <<<
#+END_SRC

This block uses all of the supported configurations, ~distro~, ~hostname~ and
 ~user~. These can be used in any combination and order.

If *all* of the given configurations match, manafiles will make sure that the
contents of the block are uncommented. If *any* of them do *not* match, then
manafiles will make sure that the contents of the block are commented.

** Compiling

*** Dependencies

- ~gcc-libs~
- (make) ~cmake~
- (make) ~git~
- (make) ~gzip~
- (optional) ~grep~
- (optional) ~pacman~ + ~pacman-contrib~
- (optional) ~apt~ + ~dpkg~

The optional requirements are for the package tracking functionality.

*** Building

To get the sources from the repository, run the following commands:

#+BEGIN_SRC shell-script
$ git clone https://github.com/riyyi/manafiles
$ cd manafiles
$ git submodule init
$ git submodule update
#+END_SRC

or

#+BEGIN_SRC shell-script
$ git clone --recursive https://github.com/riyyi/manafiles
$ cd manafiles
#+END_SRC

**** Compiling

To compile, run the following commands:

#+BEGIN_SRC shell-script
$ mkdir build
$ cd build
$ cmake ..
$ make
# Optional. This will install the manafiles executable in /usr/bin
$ sudo make install
#+END_SRC

*** Uninstalling

To uninstall, run the following commands:

*Warning*: ~make uninstall~ will try to delete all files listed in the
~install_manifest.txt~ file inside your ~build~ folder. Make sure you first
check that it won't delete any important files.

#+BEGIN_SRC shell-script
$ cd build
$ sudo make uninstall
#+END_SRC