aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMohammad Akhlaghi <mohammad@akhlaghi.org>2019-07-29 13:50:07 +0100
committerMohammad Akhlaghi <mohammad@akhlaghi.org>2019-07-29 13:50:07 +0100
commit41dbf93ea0173f82b552402aa9d6636e1f1e2972 (patch)
tree2a36756e9a0cfefd0db42a9f72e57dbf65ace010
parent6ae3d6425dff2dcc5bdb61a2c512508b0a066551 (diff)
Added explanation on .file-metadata within README-hacking.md
Until now there was no clear explanation on `.file-metadata' within the project. But since it sometimes appears in the Git changed files and its binary, it was necessary to add a short explanation to inform users. With this commit a section has been added to the "Project architecture" section of `README-hacking.md' to give some context on what it is and how to deal with it. This was suggested by Hamed Altafi.
-rw-r--r--README-hacking.md36
1 files changed, 36 insertions, 0 deletions
diff --git a/README-hacking.md b/README-hacking.md
index cf2e332..e836f36 100644
--- a/README-hacking.md
+++ b/README-hacking.md
@@ -409,6 +409,42 @@ project is designed to grow in this framework.
+File modification dates (meta data)
+-----------------------------------
+
+While git does an excellent job at keeping a history of the contents of
+files, it makes no effort in keeping the file meta data, and in particular
+the dates of files. Therefore when you checkout to a different branch,
+files that are re-written by Git will have a newer date than the other
+project files. However, file dates are important in the current design of
+the template: Make uses file dates of the pre-requisits and targets to see
+if the target should be re-built.
+
+To fix this problem, for this template we use a forked version of
+[Metastore](https://github.com/mohammad-akhlaghi/metastore). Metastore use
+a binary database file (which is called `.file-metadata`) to keep the
+modification dates of all the files under version control. This file is
+also under version control, but is hidden (because it shouldn't be modified
+by hand). During the project's configuration, the template installs to Git
+hooks to run Metastore 1) before making a commit to update its database
+with the file dates in a branch, and 2) after doing a checkout, to reset
+the file-dates after the checkout is complete and re-set the file dates
+back to what they were.
+
+In practice, Metastore should work almost fully invisiablly within your
+project. The only place you might notice its presence is that you'll see
+`.file-metadata` in the list of modified/staged files (commonly after
+merging your branches). Since its a binary file, Git also won't show you
+the changed contents. In a merge, you can simply accept any changes with
+`git add -u`. But if Git is telling you that it has changed without a merge
+(for example if you started a commit, but cancelled it in the middle), you
+can just do `git checkout .file-metadata` and set it back to its original
+state.
+
+
+
+
+
Summary
-------