This document describes the internal operation and components of the Taskfile makefile. Use this document as a reference in support of the higher level discussion of Taskfile customization.
Defines the default flags for make. For Taskfile, this is “-j4” but you can use more or less depending on your system.
Specifies the top level of the file system tree where all files that might include task items. Consider using a path like “~/wiki”, “~/deft”, “~/notes”, “~/writing” or wherever your working text and project planning files live.
The directory where Taskfile stores the cached extraction of task items from the SOURCE files. Ensure that the Taskfile cache is not tracked in version control. Consider using “.git/taskfile-cache” or place the CACHE path in your .gitignore or other similar exclusion file.
Typically this is “todo” and represents the name of the file where Taskfile writes it output.
This variable does not include the file extension.
Specifies the file extension for the of the files that contain the task list. This extension is also added. to the file name of the output file, and should not contain a “.” character.
Taskfile can only look for todo items with one extension, while this might present as a limitation, it ensures that Taskfile will only scan files that might have task items.
The full path, including file name, of the file where Taskfile will write the tasklist.
The default value for this variable is “$(SOURCE)/$(OUTPUT_FILENAME).$(EXTENSION)” and Taskfile will set this value if you do not set another value.
The default value for this variable is $(SOURCE)/$(OUTPUT_FILENANE), although you can override this value.
Defines a target to build for project specific output.
Typically a distinct makefile (e.g. a separate Taskfile instance) builds these projects specific lists. This and PROJECTS_MAKEFILE simply provide pointers to the other Taskfile instance to provide a centralized user interface.
The path to a “projects” taksfile’s directory context. Called as “make -C $(PROJECTS_MAKECONTEXT)”. This line is, however, commented out in the distributed version of taskfile.
Defines the search pattern for a grep command that finds the items Taskfile aggregates as “task items.” Taskfile calls this grep in the following form, with the KEYWORDS variable:
grep -E "($(KEYWORDS)).*"
The default expression is:
^TODO|^DEV|^FIXME|^WRITE|^EDIT|^FUTURE|^FROZEN|WORK
Modify the expression as needed.
Note
Taskfile sorts the output of grep when making the task list, which may impact how your organize your Taskfile query. Furthermore, regular expressions that anchor the search pattern (i.e. “^” for the beginning of the line, or “$” for the end of the line,) often show better performance, depending on the structure of your search content.
Holds a name for the “future” filter, used to create a secondary list of non- or less-actionable items.
Note
The default distribution of tasklist has no enabled targets that build the FUTURE_FILTER task lists. If you want to build a future task list, you will need to un-comment these sections. See the “Setup and Configuration” document for more information on this process.
Holds a list of keywords, passed as in “KEYWORDS” to grep. Used to
Note
There are no active targets that build the “future” versions of the task list, as future task lists require some measure of customization. See the “Setup and Configuration” document for more information on this process.
However, items that use one of these keywords are not included in the primary tasklist.
As FUTURE_FILTER, WORK_FILTER makes it possible to build tasklists from work-based tasks. Whereas the $(FUTURE_OUTPUT) (using FUTURE_FILTER) builds a separate tasklist, based on a special keywords, $(WORK_OUTPUT) using WORK_FILTER creates a separate tasklist by filtering out some items based on their location in SOURCE.
Note
There are no active targets that build “work” tasklists in default taskfile, because work tasklists require some measure of customization. However, no items in locations that include the WORK_FILTER term will appear in the primary taskfile.
See also
Consider the “Setup and Configuration” document for instructions regarding configuring the work tasklists.
Defines the location for the “future” task list. In the default distribution of Tasklist, this variable has a value of:
$(EXTRA_OUTPUT_DIR)/$(FUTURE_FILTER).$(EXTENSION)
In most cases you will not need or want to modify this value. This variable expands to a path of “~/wiki/todo/future.mdwn” given the default configuration.
See also
The following variables, for documentation of the default value of this variables:
Additionally, consider the commented $(FUTURE_OUTPUT) target in the default distribution for an idea of the future tasklist’s implementation.
Note
There are no active targets that build the “future” versions of the task list, as future task lists require some measure of customization. See the “Setup and Configuration” document for more information on this process.
Defines the location for the file where taskfile writes the work tasklist. The default value for this variable is as follows:
$(SOURCE)/$(WORK_FILTER)/$(OUTPUT_FILE_NAME).$(EXTENSION)
In most cases you will not need or want to modify this value. Given the default values, this expands to “~/wiki/work/todo.mdwn” in the default configuration.
See also
The following variables, for documentation of the default values for these variables:
Additionally, consider the commented $(WORK_OUTPUT) target in the default distribution for an idea of the work tasklist’s implementation.
Note
There are no active targets that build the “future” versions of the task list, as future task lists require some measure of customization. See the “Setup and Configuration” document for more information on this process.
Defines a directory within the SOURCE directory that holds. additional outputs and dependent files. The $(FUTURE_OUTPUT) builds into this directory, and a number of “template” files are in this directory. The SOURCES does not include items from this directory.
In the default configuration EXTRA_OUTPUT_DIR has the following value:
$(SOURCE)/$(OUTPUT_FILENANE)
If this variable isn’t defined in the beginning section of the taskfile, Taskfile will provide a default.
Taskfile supplies default values for the following values that are necessary for Taskfile operation, if you do not define custom values at the beginning of the file.
Unless set at the beginning of the file, the value of OUTPUT is “$(SOURCE)/$(OUTPUT_FILENAME).$(EXTENSION)”.
Unless set at the beginning of the file, the value of EXTRA_OUTPUT_DIR is “$(SOURCE)/$(OUTPUT_FILENANE)”.
See also
EXTRA_OUTPUT_DIR and the following variables that affect the value of EXTRA_OUTPUT_DIR in the default configuration:
The TMPL_DIR variable only appers in the project-specific default taskfile. In the default setting this path should match EXTRA_OUTPUT_DIR in the main Taskfile.
Unless set at the beginning of the file, the value of OUTPUT_FILE_NAME is “todo“
See also
The following variables use computed forms to generate lists or functions which underpin the operation of the targets that produce the tasklist.
Generates a list files that end with the EXTENSION. Excludes the output filneame and some temporary files. Taskfile computes SOURCES using the find command and filters the results with grep. The value of this variable is:
$(shell find $(SOURCE) -name "*$(EXTENSION)" -not \( -name ".\#*" \) | grep -v "$(OUTPUT_FILE_NAME)")
Returns a list of all directories, with recursive resolution that may contain source files. SOURCEDIR only appears in the CACHE_DIRS variable. It has the following value:
$(shell find $(SOURCE) -type d -not \( -name ".*" -prune \) -not \( -name "$(OUTPUT_FILE_NAME)" \))
Using GNU Make’s string substitution function, CACHE_DIRS generates a list of directories but substitutes the path of the top level SOURCE directory for the name of the CACHE directory in the value of SOURCEDIR. The actual value as specified is:
$(subst $(SOURCE),$(CACHE),$(SOURCEDIR))
This variable ensures Taskfile creates all required directories in the task cache before attempting to write files.
Using a nested string substitution, CACHE_INDEX_FILES replaces CACHE with SOURCE, and ”.:var:EXTENSION” with ”.:var:OUTPUT_FILE_NAME” for all of the files in the SOURCES directory that have end with the EXTENSION. For instance, given the default configuration and a file in SOURCES such as “~/wiki/shopping.mdwn”, this will become “.git/tasklist-build/shopping.todo”. The code itself is:
$(subst $(SOURCE),$(CACHE),$(subst .$(EXTENSION),.$(OUTPUT_FILE_NAME),$(wildcard $(SOURCES)/*.$(EXTENSION))))
Defines a shell function/loop for use in the cleanup routines that deletes files in the CACHE` directory if they do not exist in the SOURCE directory.
In some cases, if you delete or move a file within the SOURCE hierarchy, stale tasks remain on the list. Use clean to run this routine.
The code that implements this function, formatted for easy reading, is as follows:
for item in `find $(CACHE)/ -name "*$(OUTPUT_FILE_NAME)"` ;
do
temp=`echo $$item | sed -e "s/$(OUTPUT_FILE_NAME)/$(EXTENSION)/" -e "s@$(CACHE)@$(SOURCE)@"`
if [[ ! -f "$$temp" ]]
then
echo "rm $$item"
rm $$item
fi
done
These targets provide an interface and outputs for Taskfile. While these targets do not write data to the cache or output, some have dependencies that may trigger a rebuild.
Returns a brief help text that lists the available build targets and a brief overview of their use.
Prints the todo list to the terminal with cat.
This target depends on OUTPUT, so will rebuild the todo list if it is out of date
Prints the work-specific todo list to the terminal with cat.
This target depends on WORK_OUTPUT, so will rebuild the work-specific todo list if it is out of date.
Note
The default distribution disables this target by default.
Prints the aggregated future-todo list to the terminal with cat.
This target depends on WORK_OUTPUT, so will rebuild the aggregated future-todo list if it is out of date.
Note
The default distribution disables this target by default.
These targets provide dependency groupings for task list to support basic operation and configuration, but do not build output directly.
Provides a single interface to build or rebuild all of the Tasklist output files and their dependencies.
This is the default target for the Taskfile makefile.
See also
all depends on the following targets:
The following dependencies are not enabled by default:
Runs a sub-make process that builds the $(CACHE)/.setup target. This creates all of the required directories and template files for the Tasklist process.
This group of targets does the actual core “work” of Taskfile: by creating the cache, collecting the task items, and aggregating the core output list.
This simple configuration target creates all required cache directories, and touches several template files that makes it possible to build the Tasklists without error.
The target creates the following directories:
And creates empty files (with the touch utility:)
Ensures that the “tmpl” file for the work-output exists. Taskfile inserts the contents of this file into the beginning of the work-output file before the task items. Taskfile does not generate work-output unless you edit the Makefile to uncomment the relevant targets.
Ensures that the “tmpl” file for the future-output exists. Taskfile interest the contents of this file into the beginning of the future-output file before the task items. Taskfile does not generate future-output unless you edit the Makefile to uncomment the relevant targets.
Taskfile creates this folder to satisfy the dependency checking for the setup target.
The build target is just an empty placeholder file.
This target depends on $(SOURCE)/%.$(EXTENSION), and is responsible for creating the cache. The cache is a mirror of all the source directory tree, except that only lines that contain a match for the regular expression specified in KEYWORDS.
The “%” character acts as a wildcard, and when used in both the target and the destination, this target ensures that Taskfile updates the cache whenever a file that matches the dependency (i.e. all files in the SOURCE directory hierarchy,) is rebuilt into a cache target.
Because of the structure of this operation, this target ensures that Taskfile only parses those files that end with EXTENSION, and that all files in the cache have a distinct extension.
Note
This target suppresses normal output and instead prints “Caching: $(CACHE)/.$(EXTENSION)”.
This target depends on CACHE_INDEX_FILES, which holds a list of files that the “$(CACHE)/%.$(OUTPUT_FILENAME)” generates.
The target performs the following three actions:
This target depends on the “$(CACHE)/$(OUTPUT_FILENAME).list” output.
The target performs the following two actions:
Copies the content of $(EXTRA_OUTPUT_DIR)/tmpl.$(OUTPUT_FILE_NAME) into the new OUTPUT file. This provides any header material.
Performs a series of transformations on the content of the “$(CACHE)/$(OUTPUT_FILENAME).list” file to remove any items that match the FUTURE_FILTER, FUTURE_KEYWORDS, or WORK_FILTER.
Finally Taskfile sorts the output and writes it to the new OUTPUT file.
Uncomment and customize these targets as necessary in taskfile.make file included in this distribution to provide these advanced aggregation features.
This target builds the file described by the variable FUTURE_OUTPUT. It depends on the $(OUTPUT) target.
Procedurally, this target is similar to the $(OUTPUT) target. $(FUTURE_OUTPUT) has the following components:
Copies the content of $(EXTRA_OUTPUT_DIR)/tmpl.$(FUTURE_FILTER) into the new FUTURE_OUTPUT file. This provides any header material.
Selects all of the lines that match FUTURE_KEYWORDS in the file built by the target $(CACHE)/$(OUTPUT_FILE_NAME).list.
Taskfile sorts these lines before writing them to the output file.
Performs a series of transformations on the content of the “$(CACHE)/$(OUTPUT_FILENAME).list” file. All transformations occur in the target file, the content in the $(CACHE)/$(OUTPUT_FILENAME).list file is not modified. These transformations to remove any items that match the WORK_FILTER, and clean up potential formatting errors.
This target builds the file described by the variable WORK_OUTPUT. It depends on the $(OUTPUT) target.
Procedurally, this target is similar to the $(OUTPUT) and $(FUTURE_OUTPUT) targets and has the following components:
Copies the content of $(EXTRA_OUTPUT_DIR)/tmpl.$(WORK_FILTER) into the new WORK_OUTPUT file. This provides header data.
Selects all of the lines that match WORK_KEYWORDS in the file built by the target $(CACHE)/$(OUTPUT_FILE_NAME).list.
Taskfile sorts these lines before writing them to the output file.
Performs a series of transformations on the content imported in from “$(CACHE)/$(OUTPUT_FILENAME).list”. All transformations occur in the target file, the content in the $(CACHE)/$(OUTPUT_FILENAME).list file is not modified.
This target, which builds the $(SOURCE)/projects.$(EXTENSION) file, calls a sub-make in the context of the directory specified by the PROJECTS_MAKECONTEXT. This assumes that, when active, there is a projects-specific Taskfile located in the PROJECTS_MAKECONTEXT.
The taskfile.projects provides an example of such a file.
These targets are useful for forcing Taskfile to delete certain files that have grown stale or that you would like to regenerate during the next build.
The clean target will delete the generated output, remove stale files from the cache, and run the setup routine. In short, this target does everything that you need short of deleting the CACHE directory to get a good build.
Runs the command specified by the CLEAN_UP_DELETED_FILES variable.
clean removes the following files directly:
When the clean operation has finished, this target runs a sub-make using the setup (in silent mode.)
The clean-output target removes the following files:
When the clean operation has finished, this target runs a sub-make using the setup (in silent mode.)
Use clean-output as a less intensive version of the clean process because of the omission of the CLEAN_UP_DELETED_FILES procedure.
The clean-setup target removes the .setup file created by the $(CACHE)/.setup target.
The clean-cache removes the CACHE directory. When the clean operation has finished, this target runs a sub-make using the setup (in silent mode.)
The clean-dirty removes the CACHE directory.
The clean target removes the following files:
Building this target will remove all files created by Taskfile.
Used by the $(CACHE)/%.$(OUTPUT_FILENAME).
$(SOURCE)/%.$(EXTENSION) provides a matching dependency for all the files specified by the SOURCES variable.