How do you manage your default packages?

[michaelblyons]

The ReadMe installation instructions work fine on a one-off basis, but I found that it was sometimes annoying to switch branches to work on language A or feature B and lose the improvements I (or one of you) made to language X or feature Y.

Do you have an interesting way of handling the way that this repository holds multiple languages?

• Please include any pros or cons you've found with your approach.
• If you have several ways, use one post for each to keep comments organized.

[michaelblyons]

Two worktrees

I use two worktrees and an integration branch for mine:

• defaults holds the main repo, where packages are symlinked to ST.
• defaults-edit is a worktree of defaults where I make edits.

$ tree -L1 projects/sublime-text/syntax/
..
├── asciidoc
├── ...
├── defaults
├── defaults-edit
├── ...
└── viml

defaults is on my integration branch¹ all the time, but defaults-edit bounces around based on what I'm working on. When I have an interesting change, I commit it and re-merge the integration branch.

I have some Git aliases in the repo's .git/config, where I pick which branches to include:

[alias]
	o = "!(pushd ../defaults && git octo && popd)"
	octo = "! \
		git checkout octopus && \
		git reset --hard upstream/master && \
		git merge --message 'git-octo merge' --rerere-autoupdate \
			`# bash/history` \
			`# c/cpp-class-meta` \
			`# lisp/errata` \
			`# ruby/regex` \
			ruby/endless-paul \
			`# upstream/develop/latex` \
			`# ismell/fix-1830` \
			`# jrappen/fix-json` \
			`# keith/cs_regex` \
			sql/hibernate \
			`# sql/select-db` \
	"

I've been doing this for at least 7 years, and maybe a few more.

How it feels

Pros

• I can use improvements from multiple branches in ST simultaneously.
• All of my work still happens in a single worktree.
• The integration branch knows what's on it, and it's only ever one commit ahead of upstream/master.
• I can run syntax tests from defaults-edit even though they're not symlinked... provided that the exact content is in the same file on defaults. I'm not sure how this works (hashing?), but it's an important part of the system.

Cons

• I have to commit changes and re-integrate to see the effects.
• Packages can have merge conflicts with each other. I usually have to pick my favorite change if this happens.

Footnotes

1. The integration branch is called octopus after the huge octopus merges it used to do. 🐙 The merges are not as massive now that we review and merge each other's work into master. Back before that, there were so many unmerged branches with good stuff. ↩

[jrappen]

I rarely check out other people's pull requests these days, mainly because there're not that many major rewrites and turn-around time has gone way down.

Those that are left, are mostly mine, but that's another issue because life happens 🤷🏼

[deathaxe]

The main repo is cloned to /data/Sublime/Packages with master branch or a preview/all branch checked out most of the time. The later one contains all changes of packages, which are symlinked from that folder.

This whole repo is symlinked to a dedicated portable ST setup as /Data/Packages with all syntax related packages from /Packages removed. Default and User folder are .gitignored. This is the final testing instance to verify all syntax-tests pass. Note, this is on Windows and spinning up a VM or struggle with WSL to run syntax-test runner locally is not a thing.

For each (group of) package(s)/syntax(es) that long running development takes place on, a separate worktree is created with only the package(s) of interest being checked out and symlinked to primary ST instance's Packages folder. Each such worktree has its own preview/<package> branch (the main of this worktree) and all sorts of wip/... and pr/... branches with experiments or fixes. The preview/<package> may end up in preview/all for cross-package testing.

So basically a separate repo for each package with its independent branching and filesystem representation.

The general workflow to create such syntax-specific repo is

cd ~/Sublime/Packages
git add worktree ../Packages_<Syntax>
cd  ../Packages_<Syntax>
git sparse-checkout init
git sparse-checkout add <Syntax>
create junction/symlink of /data/Sublime/Packages_<Syntax>/<Syntax> in %APPDATA%/Sublime Text/Packages/

The tricky part is to add relevant/related packages to the sparse-checkout, if a change requires modification to multiple syntaxes in the same PR. My Packages_HTML, for instance, contains HTML, PHP, and Rails packages.

Example Worktree Structure:

• data
  • Packages (main repo)
  • Packages_CSS (worktree of Packages)
    • CSS
  • Packages_Java
    • Java
  • Packages_HTML (worktree of Packages)
    • ASP
    • HTML
    • PHP

Thanks to ST and SM resolving symlinks, working within ST is then quite natural for each symlinked package.