[DOC] fix erronously named option "user" to "owner" in the docstring of "files.find" in salt/modules/files.py #67912

dnessett · 2025-03-22T23:08:59Z

What does this PR do?

Fixes a documentation error in salt/modules/files.py. Specifically, it corrects the erroneously named option "user" to "owner".

What issues does this PR fix or reference?

[Doc] 67911

Merge requirements satisfied?

[NOTICE] Bug fixes or features added to Salt require tests.

Docs
Changelog - https://docs.saltproject.io/en/master/topics/development/changelog.html
Tests written/updated

Commits signed with GPG?

No

associated with def find(path, *args, **kwargs) in file.py

salt/modules/file.py

whytewolf · 2025-04-14T19:30:06Z

you need to fix pre-commit.

dnessett · 2025-04-14T21:04:52Z

you need to fix pre-commit.

Happy too. But, I don't know what the problem is. Do I execute pre-commit install again? Do I reinstall pre-commit with apt?

whytewolf · 2025-04-14T21:30:30Z

you need to fix pre-commit.

Happy too. But, I don't know what the problem is. Do I execute pre-commit install again? Do I reinstall pre-commit with apt?

nothing that drastic. this is the issue.

 fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook

Fixing changelog/67911.fixed.md

most likely you either had too many lines. or didn't have a line ending on the end of the file.

dnessett · 2025-04-14T21:55:10Z

you need to fix pre-commit.

Happy too. But, I don't know what the problem is. Do I execute pre-commit install again? Do I reinstall pre-commit with apt?

nothing that drastic. this is the issue.
 fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook

Fixing changelog/67911.fixed.md
most likely you either had too many lines. or didn't have a line ending on the end of the file.

I failed to install pre-commit to the branch containing the fixes for 67911. I did that, added an end of line to the file salt/modules/file.py, did a git add for file.py then committed. Pre-install then ran during the commit, but it output the following:

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt$ git commit
check for merge conflicts................................................Passed
trim trailing whitespace.................................................Passed
mixed line ending........................................................Passed
fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook

Fixing salt/modules/file.py

I don't know if the output "Fixing salt/modules/file.py" means pre-commit fixed the problem or if "fix end of files.........................................................Failed" means there is still a problem. I need some guidance on this before I do the push to my repo on GitHub.

dnessett · 2025-04-14T22:04:23Z

OK, I looked at file.py after pre-commit ran and it deleted the newline after the last non-empty line in the file. So, I must have misinterpreted, "most likely you either had too many lines. or didn't have a line ending on the end of the file." Can you explain or point me to the requirements for end-of-file on salt files?

twangboy · 2025-04-15T20:25:45Z

I think we require a single new line at the end of python files.

dnessett · 2025-04-15T21:02:25Z

I think we require a single new line at the end of python files.

Thanks. That is what I thought. However, I added a single blank line at the end of file.py (which didn't have one) and it seems pre-commit removed it when I committed the change. Also after pre-commit runs, the commit doesn't and file.py is in a strange state in which it is listed as "Changes to be committed:" as well as "Changes not staged for commit:". Here is the record showing this:

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git status
On branch bugfix-67911
nothing to commit, working tree clean
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ tail -5 file.py

            total_size += stat_structure.st_size

    ret = total_size
    return ret
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ vi file.py
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ tail -5 file.py
            total_size += stat_structure.st_size

    ret = total_size
    return ret

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git add file.py
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git commit
check for merge conflicts................................................Passed
trim trailing whitespace.................................................Passed
mixed line ending........................................................Passed
fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook

Fixing salt/modules/file.py

<elided most of pre-commit output>

Lint Salt................................................................Passed
Lint Tests...........................................(no files to check)Skipped
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git status
On branch bugfix-67911
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file.py

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   file.py

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ tail -5 file.py

            total_size += stat_structure.st_size

    ret = total_size
    return ret
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$

whytewolf · 2025-04-15T21:43:27Z

I think we require a single new line at the end of python files.

Thanks. That is what I thought. However, I added a single blank line at the end of file.py (which didn't have one) and it seems pre-commit removed it when I committed the change. Also after pre-commit runs, the commit doesn't and file.py is in a strange state in which it is listed as "Changes to be committed:" as well as "Changes not staged for commit:". Here is the record showing this:

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git status
On branch bugfix-67911
nothing to commit, working tree clean
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ tail -5 file.py

            total_size += stat_structure.st_size

    ret = total_size
    return ret
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ vi file.py
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ tail -5 file.py
            total_size += stat_structure.st_size

    ret = total_size
    return ret

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git add file.py
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git commit
check for merge conflicts................................................Passed
trim trailing whitespace.................................................Passed
mixed line ending........................................................Passed
fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook

Fixing salt/modules/file.py

<elided most of pre-commit output>

Lint Salt................................................................Passed
Lint Tests...........................................(no files to check)Skipped
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ git status
On branch bugfix-67911
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file.py

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   file.py

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$ tail -5 file.py

            total_size += stat_structure.st_size

    ret = total_size
    return ret
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt/salt/modules$

pre-commit can be finicky to work with. what i normally do is instead of committing right away. i run git add . command then run pre-commit manually. if it does changes i then run git add . again after and rerun pre-commit again. once pre-commit runs clean i will then commit the change. this lets me make sure each commit passes pre-commit.

pre-commit will make some changes to files. but it doesn't add them to the commit on its own. so you have to account for it when working with it and git.

dnessett · 2025-04-15T22:22:07Z

pre-commit can be finicky to work with. what i normally do is instead of committing right away. i run git add . command then run pre-commit manually. if it does changes i then run git add . again after and rerun pre-commit again. once pre-commit runs clean i will then commit the change. this lets me make sure each commit passes pre-commit.

pre-commit will make some changes to files. but it doesn't add them to the commit on its own. so you have to account for it when working with it and git.

I tried your suggestion. pre-commit ran and deleted the newline at the end of file.py. Then I ran pre-commit again and it passed. However, git status showed no files modified, so I couldn't add file.py and do the commit. Is it possible that pre-commit doesn't want a newline at the end of the file? If so, the failure of pre-commit when running the PR is hard to understand. Might the version of pre-commit which runs for the PR not be the same as the version of pre-commit installed on linux using apt? The version installed on my linux machine is 4.0.1

whytewolf · 2025-04-15T22:35:19Z

pre-commit can be finicky to work with. what i normally do is instead of committing right away. i run git add . command then run pre-commit manually. if it does changes i then run git add . again after and rerun pre-commit again. once pre-commit runs clean i will then commit the change. this lets me make sure each commit passes pre-commit.
pre-commit will make some changes to files. but it doesn't add them to the commit on its own. so you have to account for it when working with it and git.

I tried your suggestion. pre-commit ran and deleted the newline at the end of file.py. Then I ran pre-commit again and it passed. However, git status showed no files modified, so I couldn't add file.py and do the commit. Is it possible that pre-commit doesn't want a newline at the end of the file? If so, the failure of pre-commit when running the PR is hard to understand. Might the version of pre-commit which runs for the PR not be the same as the version of pre-commit installed on linux using apt? The version installed on my linux machine is 4.0.1

precommit in the PR isn't failing on file.py. it is failing on your changelog.

also once you get a pre-commit to run clean and git add works. and you get a commit in place. don't forget to push to github. the PR won't update till you do the push.

dnessett · 2025-04-15T23:04:44Z

precommit in the PR isn't failing on file.py. it is failing on your changelog.

also once you get a pre-commit to run clean and git add works. and you get a commit in place. don't forget to push to github. the PR won't update till you do the push.

I looked at the changelog entry for 67911 ( 67911.fixed.md on https://github.com/dnessett/salt/ - changelog directory for branch bug fix-67911 - from which I did the pull request) and it does not have a newline after the changelog description. I then looked at the file on my local machine and it does have a newline after the description. So, I am speculating that running pre-commit on the PR side deleted the newline from the changelog file on my local repository on GitHub. I cannot commit the local file and push it, since git detects no changes to its content. pre-commit on my local machine does not complain that there is a newline after the description on 67911.fixed.md, which is puzzling. I am now completely confused.

whytewolf · 2025-04-15T23:13:11Z

precommit in the PR isn't failing on file.py. it is failing on your changelog.
also once you get a pre-commit to run clean and git add works. and you get a commit in place. don't forget to push to github. the PR won't update till you do the push.

I looked at the changelog entry for 67911 ( 67911.fixed.md on https://github.com/dnessett/salt/ - changelog directory for branch bug fix-67911 - from which I did the pull request) and it does not have a newline after the changelog description. I then looked at the file on my local machine and it does have a newline after the description. So, I am speculating that running pre-commit on the PR side deleted the newline from the changelog file on my local repository on GitHub. I cannot commit the local file and push it, since git detects no changes to its content. pre-commit on my local machine does not complain that there is a newline after the description on 67911.fixed.md, which is puzzling. I am now completely confused.

you have most likely rerun pre-commit so many times at this point that it is fixed in your local system. don't think about what it is trying to do and just let it do it.

dnessett · 2025-04-15T23:18:21Z

you have most likely rerun pre-commit so many times at this point that it is fixed in your local system. don't think about what it is trying to do and just let it do it.

Thinking about this, to get my local system in sync with the repo branch, should I delete the newline on my local system changelog entry, git add that entry, run pre-commit until it is satisfied then commit the change and finally push the result? This will not change the file on my local repository, but will get my local machine and repo in sync.

whytewolf · 2025-04-15T23:37:42Z

what does git status give? without touching anything.

dnessett · 2025-04-15T23:59:39Z

what does git status give? without touching anything.

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt$ git status
On branch bugfix-67911
nothing to commit, working tree clean
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt$

whytewolf · 2025-04-16T00:17:35Z

weird ... your git isn't tracking upstream?

output of these?

git branch -vv
git rev-parse --symbolic-full-name "@{u}"

dnessett · 2025-04-16T00:22:46Z

weird ... your git isn't tracking upstream?

output of these?
git branch -vv
git rev-parse --symbolic-full-name "@{u}"

(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt$ git branch -vv
  3006.x       685d330cc0 [origin/3006.x] Fix some lint
* bugfix-67911 804be91e20 Merge branch 'master' into bugfix-67911
  master       c672f97fe0 [origin/master] Merge branch 'saltstack:master' into master
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt$ git rev-parse --symbolic-full-name "@{u}"
fatal: no upstream configured for branch 'bugfix-67911'
(salt) dan@Eclipse-Salt:~/SaltSource/bugfix-67911/salt$

It seems I forgot to set upstream for the branch.

Actually, I did but set it to saltstack/salt

git remote add upstream https://github.com/saltstack/salt.git

whytewolf · 2025-04-16T00:29:45Z

looks like bugfix-67911 is not set to track origin/bugfix-67911

git branch --set-upstream-to origin/bugfix-67911 should fix that

also next time you create a new branch locally use -u when you push it for the first time to origin. that will set git to track the github version and see differences between origin and local

dnessett · 2025-04-16T00:35:42Z

looks like bugfix-67911 is not set to track origin/bugfix-67911

git branch --set-upstream-to origin/bugfix-67911 should fix that

also next time you create a new branch locally use -u when you push it for the first time to origin. that will set git to track the github version and see differences between origin and local

OK. Thanks,

FYI. I have to step a way for several hours.

dnessett · 2025-04-16T20:07:56Z

I executed git branch --set-upstream-to origin/bugfix-67911, as suggested. then executed git fetch upstream. My local copy of salt/changelog/67911.fixed.md was still out of sync with the repo copy having no extra line at its end, whereas my local copy did. So, I deleted the extra line from my local copy, git added it, commit-ed the change and then pushed to my local repo. This sync'd the local and repo copies of bugfix-6791.

I think the reason the git fetch did not sync the two copies is when the PR pre-commit ran, it changed the copy of 67911.fixed.md on my repo without using git commit logic. This caused the two copies to go out of sync. The git fetch upstream (I am speculating here) doesn't do a complete diff of the local and repo copies, so whengit fetch upstream was executed, there were no differences in the commit history, so git thinks both copies are in sync. Hence the necessity of manually fixing the problem.

whytewolf · 2025-04-16T22:50:51Z

so, about your speculation.

about what fetch does.
"Fetch branches and/or tags (collectively, "refs") from one or more other repositories, along with the objects necessary to complete their histories. Remote-tracking branches are updated (see the description of below for ways to control this behavior)."

notice that it only lists remote-tracking branches as being updated. other wise it just downloads the meta data for branchs/tags. as noted your bugfix-67911 local branch wasn't tracking a remote. so it wouldn't be syncing. you also were fetching upstream, your github account is origin not upstream. personally I use git fetch --all if i use git fetch which is also rare.

so what happened. your local copy was not tracking origin. you made updates. then didn't push those updates to origin. so they came out of sync. then started into a cycle of git commit, git fetch. trying to understand what was happening. but since git fetch doesn't do anything for local branches that are not tracking the git fetch did absolutely nothing.

so just remember. git commit, then git push. so that you upload your local changes to the origin remote. also make sure your local branch IS tracking a remote branch. [there are reasons, and times when a local branch shouldn't track a remote branch, but that is way beyond this advice.]

git fetch is for when you want to pull from remote before doing a rebase or merge.

dnessett · 2025-04-16T22:59:06Z

so, about your speculation.

about what fetch does. "Fetch branches and/or tags (collectively, "refs") from one or more other repositories, along with the objects necessary to complete their histories. Remote-tracking branches are updated (see the description of below for ways to control this behavior)."

notice that it only lists remote-tracking branches as being updated. other wise it just downloads the meta data for branchs/tags. as noted your bugfix-67911 local branch wasn't tracking a remote. so it wouldn't be syncing. you also were fetching upstream, your github account is origin not upstream. personally I use git fetch --all if i use git fetch which is also rare.

so what happened. your local copy was not tracking origin. you made updates. then didn't push those updates to origin. so they came out of sync. then started into a cycle of git commit, git fetch. trying to understand what was happening. but since git fetch doesn't do anything for local branches that are not tracking the git fetch did absolutely nothing.

so just remember. git commit, then git push. so that you upload your local changes to the origin remote. also make sure your local branch IS tracking a remote branch. [there are reasons, and times when a local branch shouldn't track a remote branch, but that is way beyond this advice.]

git fetch is for when you want to pull from remote before doing a rebase or merge.

Thanks for the explanation.

fix erronously named option "user" to "owner" in the docstring

63f2782

associated with def find(path, *args, **kwargs) in file.py

dnessett requested a review from a team as a code owner March 22, 2025 23:09

added changelog file for 67911 documentation fix.

ced276c

dnessett mentioned this pull request Mar 24, 2025

[DOCS] option "user" is misnamed. It should be "owner" #67911

Open

twangboy requested changes Mar 25, 2025

View reviewed changes

salt/modules/file.py Outdated Show resolved Hide resolved

Lined up ':' and '=' or owner in file.py

f8a9aa2

twangboy previously approved these changes Mar 26, 2025

View reviewed changes

dmurphy18 changed the title ~~fix erronously named option "user" to "owner" in the docstring of "files.find" in salt/modules/files.py~~ [DOC] fix erronously named option "user" to "owner" in the docstring of "files.find" in salt/modules/files.py Mar 26, 2025

dmurphy18 added this to the Argon v3008.0 milestone Mar 26, 2025

dmurphy18 added Documentation Relates to Salt documentation doc-correction docu page has an error or deadlink and removed doc-correction docu page has an error or deadlink labels Mar 26, 2025

dmurphy18 approved these changes Mar 26, 2025

View reviewed changes

dmurphy18 had a problem deploying to ci March 26, 2025 17:06 — with GitHub Actions Error

Merge branch 'master' into bugfix-67911

804be91

twangboy temporarily deployed to ci March 26, 2025 17:06 — with GitHub Actions Inactive

twangboy temporarily deployed to ci March 26, 2025 17:44 — with GitHub Actions Inactive

trimmed newline from end of file.

49339ce

dnessett dismissed twangboy’s stale review via 49339ce April 16, 2025 19:54

dnessett temporarily deployed to ci April 16, 2025 20:57 — with GitHub Actions Inactive

twangboy approved these changes Apr 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] fix erronously named option "user" to "owner" in the docstring of "files.find" in salt/modules/files.py #67912

[DOC] fix erronously named option "user" to "owner" in the docstring of "files.find" in salt/modules/files.py #67912

dnessett commented Mar 22, 2025 •

edited

Loading

whytewolf commented Apr 14, 2025

dnessett commented Apr 14, 2025

whytewolf commented Apr 14, 2025

dnessett commented Apr 14, 2025 •

edited

Loading

dnessett commented Apr 14, 2025

twangboy commented Apr 15, 2025

dnessett commented Apr 15, 2025

whytewolf commented Apr 15, 2025 •

edited

Loading

dnessett commented Apr 15, 2025 •

edited

Loading

whytewolf commented Apr 15, 2025 •

edited

Loading

dnessett commented Apr 15, 2025 •

edited

Loading

whytewolf commented Apr 15, 2025

dnessett commented Apr 15, 2025

whytewolf commented Apr 15, 2025

dnessett commented Apr 15, 2025 •

edited

Loading

whytewolf commented Apr 16, 2025

dnessett commented Apr 16, 2025 •

edited

Loading

whytewolf commented Apr 16, 2025 •

edited

Loading

dnessett commented Apr 16, 2025

dnessett commented Apr 16, 2025 •

edited

Loading

whytewolf commented Apr 16, 2025

dnessett commented Apr 16, 2025

[DOC] fix erronously named option "user" to "owner" in the docstring of "files.find" in salt/modules/files.py #67912

Are you sure you want to change the base?

[DOC] fix erronously named option "user" to "owner" in the docstring of "files.find" in salt/modules/files.py #67912

Conversation

dnessett commented Mar 22, 2025 • edited Loading

What does this PR do?

What issues does this PR fix or reference?

Merge requirements satisfied?

Commits signed with GPG?

whytewolf commented Apr 14, 2025

dnessett commented Apr 14, 2025

whytewolf commented Apr 14, 2025

dnessett commented Apr 14, 2025 • edited Loading

dnessett commented Apr 14, 2025

twangboy commented Apr 15, 2025

dnessett commented Apr 15, 2025

whytewolf commented Apr 15, 2025 • edited Loading

dnessett commented Apr 15, 2025 • edited Loading

whytewolf commented Apr 15, 2025 • edited Loading

dnessett commented Apr 15, 2025 • edited Loading

whytewolf commented Apr 15, 2025

dnessett commented Apr 15, 2025

whytewolf commented Apr 15, 2025

dnessett commented Apr 15, 2025 • edited Loading

whytewolf commented Apr 16, 2025

dnessett commented Apr 16, 2025 • edited Loading

whytewolf commented Apr 16, 2025 • edited Loading

dnessett commented Apr 16, 2025

dnessett commented Apr 16, 2025 • edited Loading

whytewolf commented Apr 16, 2025

dnessett commented Apr 16, 2025

dnessett commented Mar 22, 2025 •

edited

Loading

dnessett commented Apr 14, 2025 •

edited

Loading

whytewolf commented Apr 15, 2025 •

edited

Loading

dnessett commented Apr 15, 2025 •

edited

Loading

whytewolf commented Apr 15, 2025 •

edited

Loading

dnessett commented Apr 15, 2025 •

edited

Loading

dnessett commented Apr 15, 2025 •

edited

Loading

dnessett commented Apr 16, 2025 •

edited

Loading

whytewolf commented Apr 16, 2025 •

edited

Loading

dnessett commented Apr 16, 2025 •

edited

Loading