README

		      ____________________________

				 DOTPUB
		       rolandog's public dotfiles

			     Rolando Garza
		      ____________________________


			       2021-12-03


Table of Contents
_________________

1. What is this?
.. 1. But,... why?
.. 2. TL;DR?
2. Downloading dotfiles
3. Installing dotfiles
4. What dotfiles are installed?
5. Pushing local changes
6. Online resources
.. 1. Programmer's dotfiles
.. 2. Online discussions or tutorials





1 What is this?
===============

  This is Rolando Garza's personal repository of public configuration
  files and utility scripts for the programs he uses on an almost daily
  basis.


1.1 But,... why?
~~~~~~~~~~~~~~~~

  The intent of sharing this publicly is that these files may hopefully
  be of some use to others.


1.2 TL;DR?
~~~~~~~~~~

  This repository is meant to be cloned inside
  `~/.local/share/dotfiles/pub/', and from that directory, package's
  dotfiles are meant to be installed by running `stow PACKAGE' inside
  that subdirectory (using [GNU Stow]).


[GNU Stow] <https://www.gnu.org/software/stow/manual/stow.html>


2 Downloading dotfiles
======================

  This repository is meant to be cloned inside
  `~/.local/share/dotfiles/pub/':

  ,----
  | git clone https://git.sr.ht/~rolandog/dotpub ~/.local/share/dotfiles/pub
  | cd ~/.local/share/dotfiles/pub
  `----


3 Installing dotfiles
=====================

  A quick way to install all the dotfiles is by running (the `SHELL'
  part is optional, but allows for the use of colors in the output):

  ,----
  | make install SHELL=/usr/bin/bash
  `----

  If, however, one wishes to only install a particular set of dotfiles
  for a particular `PACKAGE', one could run:

  ,----
  | stow PACKAGE
  `----


4 What dotfiles are installed?
==============================

  GNU Stow is a handy utility that lets us package a directory structure
  inside a folder, and it will create symbolic links to the files and
  folders inside our virtual package.

  In our case, this directory (`$HOME/.dotfiles/.pub/') is configured to
  have stow treat it as the source, and to treat `$HOME' as its target.

  For a given `PACKAGE':
  - The file `~/.local/share/dotfiles/pub/PACKAGE/.config/hello/world'
  - Will end in `~/.config/hello/world'

  Here is an overview of the 'branches' that will be 'transplanted'.
  ,----
  | /home/rolandog/.local/share/dotfiles/pub
  | |-- applications/
  | |   `-- .local/
  | |       `-- share/
  | |-- bash/
  | |   `-- .config/
  | |       `-- bash/
  | |-- emacs/
  | |   `-- .config/
  | |       `-- emacs/
  | |-- firewall/
  | |   `-- .local/
  | |       `-- bin/
  | |-- gpg/
  | |   `-- .gnupg/
  | |-- htop/
  | |   `-- .config/
  | |       `-- htop/
  | |-- lynx/
  | |-- make/
  | |-- org/
  | |   `-- .local/
  | |       `-- share/
  | |-- pandoc/
  | |   `-- .local/
  | |       `-- share/
  | |-- python/
  | |   `-- .config/
  | |       `-- python/
  | |-- stow/
  | |-- user-dirs/
  | |   `-- .config/
  | |-- vim/
  | |   `-- .config/
  | |       `-- vim/
  | `-- youtube-dl/
  |     `-- .config/
  | 	`-- youtube-dl/
  `----


5 Pushing local changes
=======================

  The first time we want to push additional changes back:

  ,----
  | git remote add origin git@git.sr.ht:~rolandog/dotpub
  | git push --set-upstream origin main
  `----


6 Online resources
==================

6.1 Programmer's dotfiles
~~~~~~~~~~~~~~~~~~~~~~~~~

  - <https://github.com/podiki/dot.me>
  - <https://github.com/kalkayan/dotfiles>
  - <https://github.com/gfarrell/dotfiles>


6.2 Online discussions or tutorials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  - <https://news.ycombinator.com/item?id=11071754>
  - <https://news.ycombinator.com/item?id=11070797>
  - <https://www.atlassian.com/git/tutorials/dotfiles>