doc: west: add note about west update --keep-descendants option #31201
Conversation
doc/guides/west/repo-tool.rst
Outdated
| A plain ``west update`` never fails because it does not trying to hold on | ||
| to your commits and simply leaves them aside. | ||
|
|
||
| ``west --keep-descendants`` offers an intermediate option that never |
There was a problem hiding this comment.
Forgot update here and above, will fix.
doc/guides/west/repo-tool.rst
Outdated
| ``git``, or you can use ``git -C <project_path> rebase --abort`` to | ||
| ignore incoming changes for the moment. | ||
|
|
||
| A plain ``west update`` never fails because it does not trying to hold on |
There was a problem hiding this comment.
Not quite: west update will fail if there are uncommitted changes in the working tree which conflict with the new HEAD.
There was a problem hiding this comment.
I'm conscious of uncommitted changes but the purpose of this new note and of the existing text right before it is to compare the different update options and uncommitted changes will make ANY update option will fail, correct? So uncommitted changes should be mentioned earlier in a non-option specific part, agreed? Not sure exactly where and how though.
So how about the following phrasing in the note:
A plain
west updatenever causes any git conflict because...
and:
west update --keep-descendantsoffers an intermediate option that never git conflicts either but...
?
There was a problem hiding this comment.
Fair. How about:
With a clean working tree, a plain ``west update`` never fails [...]
marc-hb
force-pushed
the
west-update-desc
branch
from
a49729d
to
b23fe6a
Compare
doc/guides/west/repo-tool.rst
Outdated
| ignore incoming changes for the moment. | ||
|
|
||
| With a clean working tree, a plain ``west update`` never fails | ||
| because it does not trying to hold on to your commits and simply |
There was a problem hiding this comment.
| because it does not trying to hold on to your commits and simply | |
| because it does not try to hold on to your commits and simply |
There was a problem hiding this comment.
Good catch, thanks for the thorough review.
I'm going to click on "commit suggestion". Last time I was in a discussion about this (a very long time ago) this project didn't allow github's most popular "squash commits" feature, it was "force pushes only (#14444) However you're the second person suggesting a fixup commit like this in just 2 days so it looks like the policy is not as strict now? Plus this is a very small commit so very little confusion in the worst of cases.
There was a problem hiding this comment.
Policy hasn't changed; you can use the commit suggestion button, but you need to fetch the resulting fix-up commits, squash, and force push.
There was a problem hiding this comment.
Done.
but you need to fetch the resulting fix-up commits, squash, and force push.
Thanks. For changing one word it's not worth it.
There was a problem hiding this comment.
Thanks. For changing one word it's not worth it.
Your call, of course; it nevertheless has value as a convenient way to provide the exact changes that are being requested.
There was a problem hiding this comment.
but you need to fetch the resulting fix-up commits, squash, and force push.
Thanks. For changing one word it's not worth it.
Agree, for a single word change like this, not so useful to hit commit button, but syntax highlighting the suggested change is very nice.
And if there are 3+ commit suggestions like this, it's much easier to just commit them all, and then git fetch + git rebase with squash is easy.
The previous and short description wasn't enough for me to understand the interesting trade-off of --keep-descendants, thanks to @mbolivar-nordic for clarifying this on Slack. For reference this option was added in west commit 11b8588303 part of zephyrproject-rtos/west#165 Signed-off-by: Marc Herbert <marc.herbert@intel.com>
marc-hb
force-pushed
the
west-update-desc
branch
from
b23fe6a
to
fa8d218
Compare
The previous and short description wasn't enough for me to understand
the interesting trade-off of --keep-descendants, thanks to
@mbolivar-nordic for clarifying this on Slack.
For reference this option was added in west commit 11b8588303 part of
zephyrproject-rtos/west#165
Signed-off-by: Marc Herbert marc.herbert@intel.com