From 24acab4fc8d407832a18442253c954c12f33f1d6 Mon Sep 17 00:00:00 2001 From: Darren 'Tadgy' Austin Date: Sat, 16 Dec 2023 21:12:45 +0000 Subject: [PATCH] Add a README.md. --- README.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7d9ebea --- /dev/null +++ b/README.md @@ -0,0 +1,132 @@ +GitAttributesDB +=============== +This is a git hook to store/restore attributes (ownerships, permissions and - on Linux - ACLs) for files stored in a git repository, and for any extra +files configured for attribute store/restore. + +This hook can be used in place of programs such as *etckeeper* to automatically (once set up) record and restore the attributes for files in your `/etc` +directory. + +I prefer this script over `etckeeper` as, once set up correctly, it is far simpler and completely automated - you do not need to run a command every time +you commit or pull changes to your `/etc` git repository. + + +Initial Set Up +-------------- +Git hooks are usually stored in the `.git/hooks` directory inside the local repository, and are not pushed to the remote when you `git push` or kept under +version control. + +As part of the initial set up, the hooks directory will be changed to be the `.githooks/` directory inside the repository root, and hooks inside that +directory put under version control - just like any files in the repository. + +The `gitattributesdb` git repository will be cloned under that directory as a git *submodule*, where the script can be called directly by the appropriate +hook files. + +Firstly, create the `.githooks/` subdirectory in your current or new git repository: +``` +mkdir .githooks/ +``` + +And add the `gitattributesdb` repository as a submodule inside the `.githooks/` directory: +``` +git submodule add https://github.com/tadgy/gitattributesdb.git .githooks/gitattributesdb +``` + +Oncw the `gitattributesdb` submodule is cloned, git hook scripts need to be added. + +You may already have hooks stored in the `.git/hooks/` directory - these will need to be moved into the `.githooks/` directory. +This command is only required if you already have hooks in your local copy of the repository: +``` +mv .git/hooks/* .githooks/ +``` + +`gitattributesdb` needs to be "hooked into" 3 git hook files: `post-checkout`, `post-merge` and `pre-commit`. +You may already have these files in the `.githooks/` directory, since they may have been moved from the `.git/hooks/` directory previously. + +If you already have those files, you only need to add the syntax to run the `gitattributesdb` script to each of those hook files. +Add the following in an appropriate place in those 3 files: +``` +.githooks/gitattributsdb/gitattributsdb "${0##*/}" +``` + +If those files do not already exist, you need to create and activate them: +``` +touch .githooks/post-checkout .githooks/post-merge .githooks/pre-commit +chmod 755 .githooks/post-checkout .githooks/post-merge .githooks/pre-commit +``` + +Open each of the files `.githooks/post-checkout`, `.githooks/post-merge` and `.githooks/pre-commit` in your favourite text editor, adding the following to +each file: +``` +#!/usr/bin/env bash + +# Store/restore the attributes of files in the repository: +.githooks/gitattributesdb/gitattributsdb "${0##*/}" +``` +Save the changes to each file. + +Configure git to use the new `.githooks/` directory rather than the default `.git/hooks` directory: +``` +git config --local core.hooksPath .githooks +``` + +Finally, add the submodule configuration and new hooks directory to the tracked files of the repository - this puts all the hooks under version control: +``` +git add .gitmodules .githooks/ +git commit -m "Added .gitmodules file, and .githooks/ directory as the git hooks directory." +``` + +Initial set up of the repository to use `gitattributesdb` is complete. +Whenever you commit changes to the repository, or pull new changes from a remote, the file attributes will be stored/restored. + + +Set Up After A New Clone +------------------------ +Git does *not* store the local configuration on the remote when you push your changes. This means that the configuration to set the hooks directory is +lost when the repository is cloned fresh. + +It also does not automatically pull any embedded submodules into the repository. + +In this situation, you need to have git pull the `gitattributesdb` submodule, and reconfigure the newly cloned repository to use the custom git hooks +directory: +``` +git submodule update --init +git config --local core.hooksPath .githooks +``` + +This will clone the *exact* commit of `gitattributesdb` that was originally added to the repository - it does not track the branch itself, so changes at the +HEAD of the branch are not reflected in the clone. In order to get the latest changes, use the update procedure detailed below. + +Once these commands have been run in the newly cloned repository (that has been initialised by the above procedure), everything is set for +`gitattributesdb` to maintain the attributes for files. + + +Updating The Embedded `gitattributesdb` Submodule +------------------------------------------------- +From time to time it is a good idea to merge any changes from the remote branch into your local submodule of `gitattributesdb`. +This allows you to pick up any fixes or updates to the tree. + +To update the submodule *from the root of the git repository*, use: +``` +(cd .githooks/gitatrributesdb && git fetch && git merge origin/master) +``` + +The submodule will now have been updated to track the latest changes in the remote "master" branch. + + +Tracking Extra Files +-------------------- +`gitattributesdb` has the ability to store/restore the attributes of extra files on the filesystem that are *not* tracked in the git repository. + +This is useful, for example, to track the attributes of `/etc/shadow`, without checking that file itself into git (and thus storing sensitive data in a +potentially publicly accessible git repository). + +To achieve this, the path to the file (relative to the root of the git repository) must be added to a special file, `.gitattributsdb-extra`, which should +be placed in the root of the repository. + +To add files to the "extra" files database, use: +``` +printf "%s" "" | base64 -w 0 >>.gitattributsdb-extra +``` +Where `` is a file relative to the repository root. + +Old files (that no longer exist on the filesystem) stored in the `.gitattributsdb-extra` file are ignored when commiting.