Discuss: Retire @button write-leoPyRef?

[Edward K. Ream]

LeoPyRef.leo defines this button. The button does the following:

- Check that the button is running from leoPy.leo, not LeoPyRef.leo.

- Updates LeoPyRef.leo using only specific subtrees of leoPy.leo.

Félix and I have noticed that sometimes this script creates large diffs between the old and new versions of LeoPyRef.leo.

Instead, the following workflow seems to work better for me:

- Save leoPy.leo as LeoPyRef.leo.

- Load the new LeoPyRef.leo.

- Delete unwanted parts of the new LeoPyRef.leo.

- Execute the git-diff command within LeoPyRef.leo.

The git-diff command will ensure I've not deleted too much :-)

More importantly, the Leonine git-diff shows me the "real" diffs, regardless of "extraneous" diffs caused by moving/alphabetizing nodes.

Summary

`@button write-leoPyRef` seems buggy in hard-to-pin-down ways.

Updating LeoPyRef.leo "by hand" is safe, provided one checks the work using Leo's git-diff command.

Your comments, please.

Edward

[Thomas Passin]

This whole subject confuses me, partly because Leo opens LeoPyRef.leo, not LeoPy.leo, when the latter is selected in File/Open Specific Leo File.  So I would never see or work on LeoPy.leo.  Almost all my work has been working on existing external files.  When I commit changes, I don't commit LeoPyRef.leo because it will load the committed changes when it loads my changed file.  The only time I would need to commit changes to LeoPyRef would be if I were to create a new external file, possibly with a new @path directory for it.  In that case, I don't see what the  write-leoPyRef button would do for me (or to LeoPyRef.leo), and I probably wouldn't even think of using it.

At a minimum, if the button is only for LeoPy.leo and not LeoPyLef.leo, it should be renamed to make that clear.  Since I don't see an actual file named "LeoPy.leo" in my clone, I assume the one is supposed to be an alias for the other.  This confuses me even more.

So as a lowly developer, I'd like to know:

- What is the difference between the LeoPyRef.leo and LeoPy.leo files, if any;

- Why is there a distinction?

- When should I use the write-leoPyRef button?

- What bad things will happen if I don't use it?

I assume there must be some non-leo-code nodes that need to be in certain places, maybe for packaging or installation, and that the button's code tries to check for them and restore them to their desired places if possible.  If that's right, no wonder it might have some bugs or quirks!

[Edward K. Ream]

On Mon, Dec 5, 2022 at 8:36 AM Thomas Passin <tbp1...@gmail.com> wrote:

This whole subject confuses me, partly because Leo opens LeoPyRef.leo, not LeoPy.leo, when the latter is selected in File/Open Specific Leo File. 

Explained briefly here.

 

So I would never see or work on LeoPy.leo.

You should always work on a local copy of LeoPyRef.leo, conventionally known as leoPy.leo.

Almost all my work has been working on existing external files.  When I commit changes, I don't commit LeoPyRef.leo because it will load the committed changes when it loads my changed file.  The only time I would need to commit changes to LeoPyRef would be if I were to create a new external file, possibly with a new @path directory for it.  In that case, I don't see what the  write-leoPyRef button would do for me (or to LeoPyRef.leo), and I probably wouldn't even think of using it.

That's right.

At a minimum, if the button is only for LeoPy.leo and not LeoPyRef.leo, it should be renamed to make that clear.  Since I don't see an actual file named "LeoPy.leo" in my clone, I assume the one is supposed to be an alias for the other.  This confuses me even more.

The renaming would be too lengthy. The script will warn and quit if it's run from LeoPyRef.leo.

So as a lowly developer, I'd like to know:

- What is the difference between the LeoPyRef.leo and LeoPy.leo files, if any;

leoPy.leo exists for your own use. Changes to LeoPyRef.leo won't interfere with it.

- Why is there a distinction?

Because git diff and git merge don't handle xml files well.

- When should I use the write-leoPyRef button?

Imo, you shouldn't. That's the point of this thread.

- What bad things will happen if I don't use it?

Nothing, if you follow the recommended new procedure.

Edward

[vitalije]

Have you tried commands `set-reference-file`, `update-ref-file`  and `read-ref-file` instead?

In all of my projects, nowadays, I have public <project>-ref.leo and private <project>.leo pair of files. Inside the private Leo file, I set the reference file to be public <project>-ref.leo file. At the same time inside public Leo file, I have defined a button node with the headline `@button n-save @key=Ctrl-s` and the body like this:

c.save()

# if using @bool tree-declutter = True uncomment next line

# clean_uas()

c.fileCommands.save_ref()

Now, every time I press Ctrl-s to save the outline, public outline is updated accordingly. After executing `git pull` , I open my private outline and execute mini buffer command `read-ref-file` to synchronize private outline with the public one. After that I continue to work on my project using only private outline.

I don't really have collaborators to work on my projects, so I can't say that this setup has been battle tested. Sometimes I work on different machines and I haven't noticed any problem synchronizing work using this method. I haven't seen unexpectedly big diffs either.

HTH Vitalije

[Thomas Passin]

I find that I can't remember what state extra untracked files are in for very long.  I usually need to stash them when I update some branch, like devel - git makes me do it before it will let me merge changes from, say, the devel branch in Leo's repo.  Pretty soon I lose track of their status.  So mostly I don't do that any more.  I foresee having the same problems with a private LeoPy.leo outline.

Usually, I use a freshly-updated branch - not devel - private to my own repo for development or experimental work.  I update it as close to submitting a PR as possible.  Any changes I make to LeoPyRef.leo can get walked back or even reset if need be.  This way I feel safe in that I won't be accidentally modifying the "real" LeoPyRef.  If I were to get stuck somehow so that my own branch got too far out of sync and couldn't be merged, I would probably copy the external files I changed somewhere outside my repo, then update to the current devel version, then restore my changes from the temporary location.  With any luck, that won't happen, but operator error is always possible so who knows?