An awesome template for your awesome library
Once you've expanded this template for your own use, you should run the Expand-Template.ps1
script to customize the template for your own project.
Further customize your repo by:
PackageLicenseExpression
property.The best way to keep your repo in sync with this template's evolving features and best practices is to periodically merge the template into your repo:
git checkout main # your default branch
git pull # make sure you're at tip
git fetch libtemplate # fetch latest Library.Template
git merge libtemplate/main
There will frequently be merge conflicts to work out, but they will be easier to resolve than running the Apply-Template.ps1
script every time, which simply blows away all your local changes with the latest from the template.
If you do not already have Library.Template history in your repo or have never completed a merge before, the above steps may produce errors. To get it working the first time, follow these steps:
git remote add libtemplate https://github.com/AArnott/Library.Template.git
git fetch libtemplate
If the git merge
step described earlier still fails for you, you may need to artificially create your first merge.
First, you must have a local clone of Library.Template on your box:
git clone https://github.com/AArnott/Library.Template.git
Make sure you have either main
checked out in that clone, as appropriate to match.
Use git rev-parse HEAD
within the Library.Template repo and record the resulting commit as we'll use it later.
Run the Apply-Template.ps1
script, passing in the path to your own Library.Template-based repo. This will blow away most customizations you may have made to your repo's build authoring. You should carefully review all changes to your repo, staging those changes that you want to keep and reverting those that remove customizations you made.
Now it's time to commit your changes. We do this in a very low-level way in order to have git record this as a merge commit even though it didn't start as a merge.
By doing this, git will allow future merges from libtemplate/main
and only new changes will be brought down, which will be much easier than the Apply-Template.ps1
script you just ran.
We create the merge commit with these commands:
git write-tree
within your repo. This will print out a git tree hash.git commit-tree -p HEAD -p A B -m "Merged latest Library.Template"
, where A
is the output from git rev-parse HEAD
that you recorded earlier, and B
is the output from your prior git write-tree
command.git merge X
where X
is the output of the git commit-tree
command.IMPORTANT: If using a pull request to get your changes into your repo, you must merge your PR. If you squash your PR, history will be lost and you will have to repeatedly resolve the same merge conflicts at the next Library.Template update.
CAUTION: when merging this for the first time, a github-hosted repo may close issues in your repo with the same number as issues that this repo closed in git commit messages.
Verify after completing your PR by visiting your github closed issues, sorted by recently updated, and reactivate any that were inadvertently closed by this merge.
This shouldn't be a recurring issue because going forward, we will avoid referencing github issues with simple #123
syntax in this repo's history.
Congratulations. You're all done.
Next time you want to sync to latest from Library.Template, you can the simple git merge
steps given at the start of this section.