workspaces 0.1.13 → 0.1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d730b2e0f349781b10fe24beefc003403f6709460fbe4e0420853988c05f1e5
-  data.tar.gz: '069ee33491c24526d1644a8877386a95720e8e61457a15296ba2da604067860a'
+  metadata.gz: 160b209187a95a674c6ce4936b4b2863ed5893ac8331f1f0345d550cf09f2f2d
+  data.tar.gz: ba7ef0dd3ed8c913ea29683f641c1d4ac314ee15a1c201dd45634d45a8a980bc
 SHA512:
-  metadata.gz: b2174d3fa1eeb55ce8fffe1dba27a7eaab267fed9904c9b216f4c256a150006d83dfb2100768dc49e473fd54f7a3e687f2dc9f9f159cb1c1df948d128079d7a3
-  data.tar.gz: 32fbfbb3e6c5334fafa03bb2bbc74f6039b4e3d17ff5a19a58422fa3314af9be0ae0eaace1d4579f2926c5a5c156f0efa074c1e9aeb2dae04d6b19f8be08a872
+  metadata.gz: 978a8f06eda4d6d9c0c443499f1cf28f41c33800b3394b40fb56dd8771e0f1283001a4e24effcb3f7c52563023a18e1f48bfe884f97bd255642ff9379b9ea095
+  data.tar.gz: 8162b0c59925b414a1af0ff511fcc6bee2d79f83bb42d452614ef68f79c7ee52e42cb89531c21c5e77b29bc76b76cdfea4f4b5fff73fff2217b49217a0321a2c

data/README.md

@@ -39,6 +39,42 @@ The returned JSON includes the workspace ID, dashboard URL, and preview URL. You
 create from a pull request with `create --pr NUMBER`, or create a new branch with
 `create --new-branch NAME --from REF`. Run `help` for lifecycle and other commands.
 
+### Git LFS
+
+If the project keeps large files in [Git LFS](https://git-lfs.com), a new workspace does not
+copy them. Creating a workspace (and fast-forwarding a PR workspace to a newer head) leaves
+those files as small pointer files, and `git status` stays clean. Without this, every
+workspace would hold a full second copy of every LFS file, even though the source
+checkout's LFS store is already shared.
+
+List the paths a workspace actually needs in `.workspaces.yml`:
+
+```yaml
+lfs:
+  fetch:
+    - eval/amc/images/golden/**
+    - spec/fixtures/images/**
+```
+
+That adds a first step, **Fetch Git LFS files**, which runs
+`git lfs pull --include=<paths>` in the workspace. It appears in the step list with its own
+log, time and place in the progress estimate like any other step, and it runs on `start` and
+`prepare` but not on `restart`. Paths are repository-relative patterns; absolute paths,
+`..`, a leading `-`, commas and control characters are rejected when the recipe loads.
+Omit `lfs` and nothing changes except that files stay as pointers.
+
+A few things worth knowing:
+
+- Files are fetched from the objects the source repository already has when it can, and from
+  the remote otherwise. If neither works (no network, or no credentials for LFS) the step
+  fails and the workspace reports it, rather than silently leaving pointers.
+- A file that is still a pointer reads as a ~130 byte text file starting with
+  `version https://git-lfs`. If a test or build reads an LFS file, add its path to
+  `lfs.fetch`.
+- To fetch more by hand in an existing workspace:
+  `workspaces exec <id> -- git lfs pull --include='path/**'`.
+- Workspaces created before this behavior keep their real files; nothing is converted.
+
 ### Step timings
 
 Per-step durations are persisted in seconds in workspace step status JSON, so they

data/lib/workspaces/recipe.rb

@@ -7,7 +7,9 @@ module Workspaces
     class Invalid < ArgumentError; end
     RESERVED_ENV = %w(WORKSPACE_ID WORKSPACE_PATH WORKSPACE_REPO_ROOT WORKSPACE_PORT WORKSPACE_URL
                       WORKSPACE_HOST WORKSPACE_CACHE_DIR WORKSPACE_RUN_ID).freeze
-    attr_reader :steps, :environment, :default_editable_env, :environment_presets
+    LFS_STEP_ID = 'lfs'.freeze
+    LFS_STEP_NAME = 'Fetch Git LFS files'.freeze
+    attr_reader :steps, :environment, :default_editable_env, :environment_presets, :lfs_fetch
 
     def initialize(root: Config.repo_root)
       @root = root
@@ -16,7 +18,9 @@ module Workspaces
       @default_editable_env = validate_editable_env!(document.fetch('default_editable_env', {}))
       @environment_presets = validate_environment_presets!(document.fetch('environment_presets', {}))
       @environment = validate_env!(document.fetch('env', {}))
+      @lfs_fetch = validate_lfs!(document.fetch('lfs', {}))
       @steps = document.fetch('steps').map { |step| validate_step!(step) }
+      @steps = [lfs_step] + @steps unless lfs_fetch.empty?
       validate_editable_overlap!
       validate_sequence!
     rescue Errno::ENOENT
@@ -29,6 +33,13 @@ module Workspaces
       restart ? steps.drop(steps.index { |step| step['background'] }) : steps
     end
 
+    # Files fetched into the workspace come from the LFS objects the source repository already
+    # has, then are linked in by `git lfs pull`; the source's store is shared by every workspace.
+    def lfs_step
+      { 'id' => LFS_STEP_ID, 'name' => LFS_STEP_NAME, 'timeout' => 600, 'env' => {}, 'background' => false,
+        'run' => ['git', 'lfs', 'pull', "--include=#{lfs_fetch.join(',')}"] }
+    end
+
     def command(step, context)
       command = step.fetch('run')
       return ['sh', '-c', command] if command.is_a?(String)
@@ -50,7 +61,7 @@ module Workspaces
         raise Invalid,
               'Configuration must be a mapping with version: 1'
       end
-      unknown_keys!(document, %w(version env default_editable_env environment_presets steps))
+      unknown_keys!(document, %w(version env default_editable_env environment_presets lfs steps))
       raise Invalid, 'steps must be a nonempty array' unless document['steps'].is_a?(Array) && !document['steps'].empty?
     end
 
@@ -100,6 +111,26 @@ module Workspaces
             'timeout applies to foreground steps, not the server lifetime'
     end
 
+    # `lfs: { fetch: [path, ...] }` names the Git LFS files a workspace needs. Everything else
+    # stays a pointer. Paths are repository-relative globs handed to `git lfs pull --include`, so
+    # they are checked for the things that would make that unsafe or surprising.
+    def validate_lfs!(value)
+      raise Invalid, 'lfs must be a mapping' unless value.is_a?(Hash)
+
+      unknown_keys!(value, %w(fetch))
+      paths = value.fetch('fetch', [])
+      raise Invalid, 'lfs.fetch must be an array of paths' unless paths.is_a?(Array)
+
+      paths.each do |path|
+        unless path.is_a?(String) && !path.strip.empty? && path == path.strip
+          raise Invalid, 'lfs.fetch paths must be nonempty trimmed strings'
+        end
+        raise Invalid, 'lfs.fetch paths cannot contain commas or control characters' if path.match?(/[,[:cntrl:]]/)
+        raise Invalid, 'lfs.fetch paths must be relative to the repository' if path.start_with?('/', '-') || path.split('/').include?('..')
+      end
+      paths.uniq
+    end
+
     def validate_env!(values)
       raise Invalid, 'env must be a mapping' unless values.is_a?(Hash)
       values.each do |key, value|

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.13'
+  VERSION = '0.1.14'
 end

data/lib/workspaces/worktree.rb

@@ -12,6 +12,12 @@ module Workspaces
     class UpdateError < StandardError; end
     AUTH_FAILURE = Regexp.union(/could not read (?:Username|Password)|terminal prompts disabled|Authentication failed/i,
                                 /Permission denied \(publickey\)|gh auth login|HTTP 401|HTTP 403/i)
+    # A project that keeps large files in Git LFS would otherwise copy every one of them into
+    # every workspace at checkout. With smudging skipped they arrive as small pointer files and
+    # `git status` stays clean, so nothing downloads until a recipe asks for it (`lfs.fetch`).
+    # Applied only where the gem writes files from Git itself; it is not applied to stash or
+    # apply, which must never swap a real file someone fetched for its pointer.
+    LFS_POINTERS_ONLY = { 'GIT_LFS_SKIP_SMUDGE' => '1' }.freeze
     METADATA = '.workspace.json'.freeze
     PR_METADATA = '.related-pr'.freeze
     attr_reader :id, :path
@@ -107,7 +113,7 @@ module Workspaces
 
       stash = save_changes
       begin
-        git!('-c', 'core.hooksPath=/dev/null', 'merge', '--ff-only', target, cwd: path)
+        git!('-c', 'core.hooksPath=/dev/null', 'merge', '--ff-only', target, cwd: path, env: LFS_POINTERS_ONLY)
       rescue CommandFailedError
         restore_changes(stash) if stash
         raise UpdateError, 'Could not fast-forward the workspace; local changes were restored'
@@ -117,8 +123,8 @@ module Workspaces
       { 'updated' => true, 'head' => target }
     end
 
-    def git!(*args, cwd: Config.repo_root)
-      output, status = Open3.capture2e(git_environment, 'git', *args, chdir: cwd.to_s)
+    def git!(*args, cwd: Config.repo_root, env: {})
+      output, status = Open3.capture2e(git_environment.merge(env), 'git', *args, chdir: cwd.to_s)
       raise_authentication_error!(output) unless status.success?
       raise CommandFailedError, "git #{args.join(' ')} failed:\n#{output}" unless status.success?
 
@@ -203,7 +209,7 @@ module Workspaces
       raise ArgumentError, 'Workspace branch must not start with a dash' if target_branch.start_with?('-')
 
       Config.worktrees_dir.mkpath
-      git!('-c', 'core.hooksPath=/dev/null', 'worktree', 'add', '-b', target_branch, path.to_s, sha)
+      git!('-c', 'core.hooksPath=/dev/null', 'worktree', 'add', '-b', target_branch, path.to_s, sha, env: LFS_POINTERS_ONLY)
     end
 
     def initialize_worktree!(source, target_branch)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.14
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack