Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve local-repo docs #906

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Improve local-repo docs #906

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
17 changes: 13 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1890,10 +1890,12 @@ meaning in a recipe (unknown keywords are ignored but preserved):

* `:local-repo`

This is the name of the local repository that is used for the
package. If a local repository by that name does not exist when you
invoke `straight-use-package`, one will be cloned according to the
package's [version-control settings][#user/recipes/vc-backends].
This is the name of the local repository (either a git directory on
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about the phrases "git directory" and "plain directory" here.
A "git directory", if I understand your intention, is just a repository.
A "plain directory" is just a directory. Those terms would probably be better. Keep in mind that other version control back ends may be implemented, so it's best to avoid referring to git directly when it's unnecessary.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I got tripped up initially because repository can mean many different things in computer science so when I was initially reading through the list of options I wasn't sure what repository meant in this context.

Maybe this would be more straightforward: "This is the path to a local vcs repository (git by default)"

Although since with :type nil it doesn't have to actually be a vcs repository so maybe something could be added to that effect.

the local file system or a plain directory on the local file system)
that is used for the package. If a local repository by that name
does not exist when you invoke `straight-use-package`, one will be
cloned according to the package's [version-control
settings][#user/recipes/vc-backends].

Multiple packages can use the same local repository. If so, then a
change to the local repository will cause both packages to be
Expand All @@ -1905,6 +1907,13 @@ meaning in a recipe (unknown keywords are ignored but preserved):
settings][#user/recipes/vc-backends], or as a last resort the
package name.

For example:

```emacs-lisp
(straight-use-package
'( example :local-repo "/home/user/repos/example.el" ))
Comment on lines +1913 to +1914
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text you added above mentions that :local-repo may be a local repository or directory, but the example is referring directly to an elisp file. Unless the directory is named "example.el", in which case the file path should end in a forward slash. It would be better to pick a name for the directory which didn't include the ".el" extension to avoid confusion, too.

Does this example work if you run it?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I intended it to be a directory named example.el, but I agree that is confusing. I haven't run straight.el stand-alone so I'm not 100% sure this example would work on it's own.

```

* `:files`

This is a list specifying which files in a package's local
Expand Down