Merge pull request #116 from JarvusInnovations/develop

Release: hologit v0.34.4

.github/workflows/docs-site.yml

@@ -0,0 +1,19 @@
+name: Docs Site
+
+on:
+  push:
+    branches: [ develop ]
+
+jobs:
+  docs-projection:
+    runs-on: ubuntu-latest
+    steps:
+    - name: 'Projecting docs-site holobranch onto gh-pages'
+      uses: JarvusInnovations/hologit@actions/projector/v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        HAB_LICENSE: accept
+      with:
+        ref: develop
+        holobranch: docs-site
+        commit-to: gh-pages

.holo/branches/docs-site.lenses/mkdocs.toml

@@ -0,0 +1,11 @@
+[hololens]
+package = "holo/lens-mkdocs"
+requirements = [
+    "mkdocs-material",
+    "mkdocs-awesome-pages-plugin",
+    "fontawesome_markdown",
+    "mdx_truly_sane_lists"
+]
+
+[hololens.output]
+merge = "replace"

.holo/branches/docs-site/_hologit.toml

@@ -0,0 +1,5 @@
+[holomapping]
+files = [
+    "docs/",
+    "mkdocs.yml"
+]

.studiorc

@@ -1,4 +1,36 @@
-hab pkg install -b \
+#!/bin/bash
+
+
+# install dependencies
+echo
+echo "--> Installing project development dependencies..."
+hab pkg install \
+    jarvus/mkdocs-studio \
+    jarvus/studio-toolkit \
     core/node \
     core/git
-    # jarvus/watchman
+
+hab pkg binlink core/node core/git
+hab pkg binlink core/coreutils env --dest /usr/bin
+
+
+# load studio toolkit
+source "$(hab pkg path jarvus/studio-toolkit)/studio.sh"
+
+
+# load MkDocs studio
+export DOCS_HOLOBRANCH="docs-site"
+source "$(hab pkg path jarvus/mkdocs-studio)/studio.sh"
+
+
+
+## final init and output
+studio-help
+
+echo
+echo "--> Developer studio ready!"
+echo "    Run `docs-watch` to start+watch MkDocs site in foreground, and access at http://localhost:9088"
+
+
+# final blank line
+echo

.vscode/launch.json

@@ -102,25 +102,25 @@
 
             "name": "project",
             "preLaunchTask": "purge hologit studios",
-            "cwd": "${workspaceFolder:hologit-debug-context}",
+            "cwd": "${workspaceFolder}",
             "env": {
                 "DEBUG": "1"
             },
             "outputCapture": "std",
             "program": "${workspaceFolder:hologit}/bin/cli.js",
             "args": [
                 "project",
-                "--working",
-                "--watch",
+                // "--working",
+                // "--watch",
                 "--debug",
                 // "--no-lens",
                 // "--fetch",
                 // "--ref=develop",
-                "--commit-to=refs/holo/branch/site",
+                // "--commit-to=refs/holo/branch/site",
                 // "--commit-message=foo",
 
                 // holobranch
-                "emergence-site"
+                "github-action-projector"
             ]
         },
         {

README.md

@@ -1,8 +1,21 @@
 # hologit
 
+Hologit lets you declaratively define virtual sub-branches (called holobranches) within any Git branch that mix together content from their host branch, content from other repositories/branches, and executable-driven transformations.
+
+## Features
+
+- Track and merge remote code from multiple sources
+- Advanced merge, filter, and sourcing strategies
+- Apply arbitrary executable steps efficiently and consistently via Chef Habitat packages
+- Content-based git-distributed caching of build steps
+- GitHub Action for materializing holobranches to real branches
+- `--watch` command to produce live updates (currently lazy/slow, theoretically can be made near-instant)
+
+## Introduction
+
 **Hologit** is a [free and open](https://www.fsf.org/about/what-is-free-software) framework for code and content automation inside your local git repository. It makes it simple, fast, and reliable for projects to automate complex editing and publishing workflows that can involve multiple source repositories, languages, and build tools. Aiming to make working on software easier for everyone—pro and beginner alike—hologit gets rid of the need to think about or even know what needs to happen after you change files. There should just be content, and it goes places when you change it.
 
-This works by enabling a project's git repository to define virtual "holobranches" that can be continuously and efficiently "projected" from a source branch. The projection process handles combining code from remote sources ("compositing") and executing build tools on the result ("lensing") to produce an output file tree and optionally commit it to a branch/ref.
+This works by enabling a project's git repository to define virtual "holobranches" that can be continuously and efficiently "projected" from any source branch. The projection process handles combining code from remote sources ("compositing") and executing build tools on the result ("lensing") to produce an output file tree and optionally commit it to a branch/ref.
 
 **Compositing** offers deeper control over which files are pulled from a remote repository and where they are integrated than [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) alone, while being more dependable and tracable than language-specific package managers like [npm](https://www.npmjs.com/) and [composer](https://getcomposer.org/). Instead of copying and moving files around on disk, hologit takes a git-native approach to minimize disk activity by computing new git trees in memory. Computed trees may be written to disk later or used as input to another process without the overhead.
 

docs/.pages

@@ -0,0 +1,4 @@
+arrange:
+- README.md
+- grand-tour
+- workflows

docs/CNAME

@@ -0,0 +1 @@
+docs.holo.sh

docs/SUMMARY.md → docs/README.md

@@ -1,4 +1,6 @@
-# Hologit Documentation
+# Getting Started
+
+Hologit lets you declaratively define virtual sub-branches within any Git branch
 
 - [Quick Start](./quick-start/README.md)
 - [Grand Tour](./grand-tour/README.md)

docs/grand-tour/.pages

@@ -0,0 +1,8 @@
+arrange:
+- README.md
+- installation.md
+- repository-setup.md
+- holobranches.md
+- holosources.md
+- hololenses.md
+- ...

docs/grand-tour/README.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This section offers a deep-dive into how each component works.

docs/grand-tour/holobranches.md

@@ -0,0 +1,3 @@
+# Holobranches
+
+Holobranches are named virtual sub-branches versioned within any Git branch. Given the name of a holobranch and a commit for a branch it's defined in, Hologit can compute the holobranch's content and outputs a Git tree.

docs/grand-tour/hololenses.md

@@ -0,0 +1,3 @@
+# Hololenses
+
+Hololenses are executable tools bound to transform some portion of a holobranch during its projectios.

docs/grand-tour/holoreactors.md

@@ -0,0 +1,3 @@
+# Holoreactors
+
+Holoreactors are running services spawned from the content within a holobranch and automatically bound to its changes.

docs/grand-tour/holosources.md

@@ -0,0 +1,58 @@
+# Holosources
+
+Holosources are named remote Git branches that content can be pulled from during projection. They can refer to any ref or hash in a remote repository, and optionally a holobranch within that.
+
+## Overriding via environment
+
+Holosources can be overridden via `HOLO_SOURCE_*` environment variables.
+
+### Variable names
+
+For example, a source named `parent-blueprint` could be overridden via `HOLO_SOURCE_PARENT_BLUEPRINT`. The transformation from source name to environment variable name is applied as follows:
+
+- Hyphens (`-`) replaced with underscores (`_`)
+- All letters capitalized
+
+### Change URL
+
+You can change just the URL, preserving declared ref+holobranch:
+
+```bash
+HOLO_SOURCE_PARENT_BLUEPRINT="https://github.com/myorg/myfork"
+```
+
+Local paths work too:
+
+```bash
+HOLO_SOURCE_PARENT_BLUEPRINT="/src/myfork"
+```
+
+### Change ref
+
+You can change just the ref, preserving declared url+holobranch:
+
+```bash
+HOLO_SOURCE_PARENT_BLUEPRINT="#refs/heads/develop"
+```
+
+### Change holobranch
+
+You can change just the holobranch, preserving declared url+ref:
+
+```bash
+HOLO_SOURCE_PARENT_BLUEPRINT="=>helm-chart"
+```
+
+### Change everything
+
+You can reconfigure an entire source:
+
+```bash
+HOLO_SOURCE_PARENT_BLUEPRINT="/src/myfork#refs/heads/develop=>helm-chart"
+```
+
+Or clear out a declared holobranch component to use a native ref directly:
+
+```bash
+HOLO_SOURCE_PARENT_BLUEPRINT="/src/myfork#refs/heads/develop=>"
+```

docs/grand-tour/repository-setup.md

@@ -0,0 +1,11 @@
+# Repository setup
+
+To enable using hologit on a repository, create `.holo/config.toml` and configure `holospace.name` within it.
+
+You can create the file yourself, or use the provided command:
+
+```bash
+git holo init
+```
+
+The name declared here is the [holosource](./holosources.md) name used to refer to the host repository.

docs/workflows/README.md

@@ -0,0 +1,3 @@
+# Introduction
+
+This section offers end-to-end examples of workflows you can implement.

mkdocs.yml

@@ -0,0 +1,46 @@
+site_name: Hologit Documentation
+site_description: Hologit lets you declaratively define virtual sub-branches within any Git branch
+site_author: Jarvus Innovations
+copyright: 2020 Jarvus Innovations
+repo_url: https://github.com/JarvusInnovations/hologit
+edit_uri: edit/develop/docs
+
+theme:
+  name: material
+  features:
+    - navigation.tabs
+  palette:
+    primary: "orange"
+    accent: "deep purple"
+
+plugins:
+  - search
+  - awesome-pages
+
+extra_javascript:
+  - https://unpkg.com/mermaid@8.5.0/dist/mermaid.min.js
+
+extra_css:
+  - https://use.fontawesome.com/releases/v5.13.0/css/all.css
+
+markdown_extensions:
+  - admonition
+  - codehilite:
+      linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tabbed
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_div_format
+  - pymdownx.smartsymbols
+  - meta
+  - toc:
+      # insert a blank space before the character
+      permalink: " ¶"
+  - smarty
+  - fontawesome_markdown
+  - mdx_truly_sane_lists

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hologit",
-  "version": "0.34.3",
+  "version": "0.34.4",
   "description": "Hologit automates the projection of layered composite file trees based on flat, declarative plans",
   "repository": "https://github.com/EmergencePlatform/hologit",
   "main": "lib/index.js",

plan.sh

@@ -10,7 +10,7 @@ pkg_build_deps=(
 
 pkg_deps=(
   core/git
-  core/node
+  jarvus/node12 # newer than core/node12
   core/hab/0.79.0 # last version before new license
 )
 

script/-studio-bootstrap

@@ -0,0 +1,74 @@
+#!/bin/bash
+
+# script/-studio-bootstrap: Check dependencies for Chef Habitat studio.
+
+set -e
+cd "$(dirname "$0")/.."
+
+
+echo
+echo "==> studio-bootstrap: verifying Docker…"
+
+if ! [ -x "$(command -v docker)" ]; then
+    echo "Please install Docker Engine: https://docs.docker.com/engine/install/"
+    exit 1
+fi
+
+if ! docker info > /dev/null 2>&1; then
+    echo "Docker Engine is not running, or your user does not have access to connect."
+    echo "Try starting Docker Engine, and adding your user to the docker group: sudo gpasswd -a $USER docker"
+    exit 1
+fi
+
+
+echo
+echo "==> studio-bootstrap: verifying Chef Habitat…"
+
+if ! [ -x "$(command -v hab)" ]; then
+    echo "Please install Chef Habitat: https://www.habitat.sh/docs/install-habitat/"
+    exit 1
+fi
+
+hab_version="$(hab --version)"
+if ! [[ $hab_version =~ ^hab[[:space:]][0-9]+\.[0-9]+\.[0-9]+/[0-9]+$ ]]; then
+    echo
+    echo "    Could not parse hab version: ${hab_version}"
+    echo "    Please install hab 1.6+"
+    exit 1
+fi
+
+hab_version="$(echo "${hab_version}" | awk '{print $2}' | awk -F'/' '{print $1}')"
+echo "    Found hab version: ${hab_version}"
+
+
+# check that node >= MAJOR.MINOR
+hab_min_major="1"
+hab_min_minor="6"
+
+IFS='.' read -ra hab_version_split <<< "${hab_version#v}"
+if [ "${hab_version_split[0]}" -lt "${hab_min_major}" ] || [[ "${hab_version_split[0]}" -le "${hab_min_major}" && "${hab_version_split[1]}" -lt "${hab_min_minor}" ]]; then
+    echo
+    echo "     Please install hab >= ${hab_min_major}.${hab_min_minor}.x"
+    exit 1
+fi
+
+if ! [ -f ~/.hab/etc/cli.toml ] || ! grep -q '^origin =' ~/.hab/etc/cli.toml; then
+    echo "Please re-run \`hab setup\` and choose to set a default origin, it can be anything"
+    exit 1
+fi
+
+_origin=$(awk -F'"' '/^origin = /{print $2}' ~/.hab/etc/cli.toml)
+
+
+echo
+echo "==> studio-bootstrap: verifying origin '${_origin}'…"
+
+if ! hab origin key export --type secret "${_origin}" > /dev/null; then
+    echo "No key has been generated for origin ${_origin}, run: hab origin key generate ${_origin}"
+    exit 1
+fi
+
+
+echo
+echo "==> studio-bootstrap: all set 👍"
+echo