ENB: Using @leo in large repos

[Edward K. Ream]

Leo 6.8.6 contains support for `@leo`, including several supporting methods. This Engineering Notebook post discusses further improvements to Leo that will become part of Leo 6.8.7.

Background

`@leo` nodes help break huge Leo outlines into a top-level outline and sub-outlines. By default, there is one sub-outline for each direct subdirectory of a top-level directory.

The top-level outline (in the top-level directory) contains `@leo` nodes (links) to the sub- outlines. The sub-outlines contain:

- One `@leo` node (the back link) pointing to the top-level outline.

- One `@clean` node for each file (of given file types) in the subdirectory and all descendant directories.

It's easy to move between these outlines. Just select an `@leo` node and execute the `open-at-leo-file` command!

The challenge

`@leo` helps break up too-large outlines into more manageable sub-outlines. This performance improvement alone makes `@leo` invaluable. For the first time, it's possible to use Leo to study huge repositories.

But we Leonistas want to do more than just study repos! To contribute to large projects, we must also update our outlines after pulling large PRs from such large repos.

Surely, such automatic updates are possible. Leo's git-related commands provide a rough template. Aha! `@leo` nodes aren't just for us humans. Scripts will find them invaluable as well.

Summary

This post is pre-writing for documenting `@leo` for Leo 6.8.6. It is also pre-writing for a new enhancement issue for Leo 6.8.7.

`@leo` links help us Leonistas navigate between outlines. That much was always obvious.

But Aha! `@leo` links can help update scripts to find sub-outlines. I'll figure out how the update scripts will work a bit later :-)

Edward

[Edward K. Ream]

On Sun, Jul 27, 2025 at 7:24 AM Edward K. Ream wrote:

Leo 6.8.6 contains support for `@leo`, including several supporting methods. This Engineering Notebook post discusses further improvements to Leo that will become part of Leo 6.8.7.

...

But we Leonistas want to do more than just study repos! To contribute to large projects, we must also update our outlines after pulling large PRs from such large repos.

Still true, but Leo's present code probably already suffices to handle updates in large repos! I had forgotten the recent improvements to @clean!

Indeed,  @bool report-changed-at-clean-nodes = True  enables the following cool features:

- Leo makes clones of all changed nodes and organizes them in the last top-level node.

- Leo calls the appropriate importer on the text of each changed node.

  This should ensure that Leo gives each added function or method its own node!

  Note that the update algorithm will automatically delete nodes as necessary.

Possible improvements

Ah, the joys of documentation. As I write this, I see two improvements are possible.

1. Leo should re-import changed nodes even if the setting above is False.

2. The c.makeLinkLeoFiles script helper (See PR #4395) should contain a kwarg that gives the value to assign to

   @bool report-changed-at-clean-nodes  This setting becomes crucial for large repos!

Summary

I'll create a new PR for improvement 1, and add improvement 2 to PR #4395.

These tweaks should not affect the release date of Leo 6.8.6.

I welcome all comments and suggestions. There is plenty of time for debate.

Edward

[Edward K. Ream]

On Monday, July 28, 2025 at 7:56:35 AM UTC-5 Edward K. Ream wrote:

> Leo should re-import changed nodes even if  [@bool report-changed-at-clean-nodes] is False.

I have just created #4400 for this tweak. If you have comments, please make them in the issue.

Edward

[Edward K. Ream]

On Mon, Jul 28, 2025 at 8:05 AM Edward K. Ream <edre...@gmail.com> wrote:

>> Leo should re-import changed nodes even if  [@bool report-changed-at-clean-nodes] is False.

> I have just created #4400 for this tweak.

My memory was faulty: PR #4395 already works as desired.

I have just closed #4400.

Edward

[Edward K. Ream]

On Monday, July 28, 2025 at 7:56:35 AM UTC-5 Edward K. Ream wrote:

> The c.makeLinkLeoFiles script helper (See PR #4395) should contain a kwarg that gives the value to assign to

> @bool report-changed-at-clean-nodes  This setting becomes crucial for large repos!

Done at rev  08dc275, part of PR  #4395.

In other words, Leo should now be able to update large repos with ease.

Let the wild rumpus continue! 

Edward