Some manipulations like wrong cp instead of using git merge, resulted in incorrect directory structure and hundreds of conflicts happened when merging back latest suru-icon-theme into our repository. In additon to all the conflicts the data structure also became:
ls icons/
16x16/ 24x24/ 256x256/ 32x32/ 48x48/ AUTHORS COPYING LICENSE_GPL3 meson.build src/
16x16@2x/ 24x24@2x/ 256x256@2x/ 32x32@2x/ 48x48@2x/ CONTRIBUTING.md LICENSE_CCBYSA meson/ scalable/ Suru/
As you can see, instead of having icons/Suru/<size>, some icons were in icons/<size> (the review should have spotted it! 
This makes the icons not being taken when merging and a mess to merge, basically.
What I did is taking back the suru icon tree state, and moving the root folder into icons/ + readding our meson changes for building it. Note that we may have lost this way some of our changes if we had any inline, please have a look if that’s the case to redo them. We didn’t have any though AFAIK (apart from the build system changes).
I realize that it was indeed a little bit difficult for some of you to merge them back. While bootstrapping again the branch, I looked at git-scm book to see if there was a better strategy, and indeed, there was one! Checking https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging “subtree merging”, you can see that we can get any merge applied with the recursive strategy into the correct subfolder (called subtree here).
So, assuming you have a suru-icon-theme remote, refreshing should be just:
git fetch suru-icon-theme
git merge -s recursive -Xsubtree=icons suru-icon-theme/master
You shouldn’t expect any post treatment like git mv any new file anymore. The only conflicts that may occur are on the meson build system files if upstream changed it as we needed to adapt it to our theme.
You can see this in this PR: Rebootstrap suru icons by didrocks · Pull Request #773 · ubuntu/yaru · GitHub
So, just to emphasize to be mindful about this directory when merging from upstream and I hope that helps clarifying how to deal with it! (maybe that can be put in CONTRIBUTING.md) 