Using Git with More than 1 Package

Submitted by Nathan Clouse on 03/25/22.

Last modified:

04/04/22

Tags:

Want to use Git with more than 1 Package? Let's review.

The process to get Git working with F&O can be a little involved and it may not make sense the first time. The issue we're presented with is that Git assumes you are starting with nothing - a directory that doesn't exist. When you fetch source code - clone it - Git wants you to clone it into a directory that doesn't exist yet. Our PackagesLocalDirectory very much so already exists. So, we have to help Git by moving in pieces of the repo into the directory then get everything back in working order. There are a few different ways to do this: The Hard Way, the easier way, and the easiest way.

The Hard Way

We'll be using https://github.com/NathanClouseAX/FOMultiPackageHardWay for this exercise. You can fork this repo and do this yourself if you'd like. All commands and instructions should be executed as an Administrator.

First, create the repo if you don't already have one. Azure DevOps will not give you an option to automatically create a .gitingore but GitHub will.

Next, clone the repo locally to a staging directory. You can use the command line or Visual Studio. Example below:

git clone --recursive https://NathanClouseAXGIT@dev.azure.com/NathanClouseAXGIT/Sample/_git/Sa... c:\temp\Sample

Next, copy the repo into PackagesLocalDirectory directory using PowerShell

copy-Item -Path "c:\temp\Sample\*" -Destination "k:\AOSService\PackagesLocalDirectory\" -Recurse -Force

Next, move into the PackagesLocalDirectory then do a Git reset.

cd k:\AOSService\PackagesLocalDirectory\
git reset --hard

Next, set permissions on .git directory to match it's parent folder.

Get-Acl -Path k:\AOSService\PackagesLocalDirectory | Set-Acl -Path k:\AOSService\PackagesLocalDirectory\.git

Next, do a pull to confirm file permissions. This will verify only admin's can interact with the repo.

git pull

Next, collect a list of custom packages for use in your .gitignore or create your custom packages inside Visual Studio. Create a .gitignore using PowerShell.

New-Item "k:\AOSService\PackagesLocalDirectory\.gitignore"

Add content to your .gitignore file based on your custom packages. sample content for a .gitingore file below for 3 packages based on GitHub. NotePad or your favorite text editor will need to run as an Administrator.

# Ignore everything
/*
# But keep custom packages and models
!/AAXWarehouseDimensionLink
AAXWarehouseDimensionLink/bin/
AAXWarehouseDimensionLink/resources/
AAXWarehouseDimensionLink/XppMetadata/
AAXWarehouseDimensionLink/BPCheck.xml
AAXWarehouseDimensionLink/BuildModelResult.xml
AAXWarehouseDimensionLink/BuildModelResult.log
AAXWarehouseDimensionLink/BuildProjectResult.err.xml
AAXWarehouseDimensionLink/BuildProjectResult.xml
AAXWarehouseDimensionLink/CompileLabels.xml
AAXWarehouseDimensionLink/*.xref
AAXWarehouseDimensionLink/*.$usr

# keep Projects
!/VSProjects

!.gitignore

Next, add the .gitignore file.

git add .gitignore

Next, delete the local repo that you cloned earlier. After that in Visual Studio, add a new local repo then commit the .gitingore file plus all packages as well then push / sync.

That's it. Now that you have the repo mapped, you can switch between branches easily.

The Easier Way

You could also use symbolic links to help out. This will allow you to manage the repo somewhere else then "link" the folders in so F&O can see them and their contents. To do this, you'll need to know how to create links as well as organize your repository in a particular way. We will be using https://github.com/NathanClouseAX/FOMultiPackageEasyWay for this exercise.

First, create a repo if you haven't already.

Next, clone locally into where ever you would like the code to live. For example, I'll be using C:\Users\Admin4b2aaec26a\source\repos\NathanClouseAX\FOMultiPackageEasyWay. This can be done via command line or using Visual Studio.

Next, add a folder named Metadata

Next, add a folder named Projects

Next, create packages and models in Visual Studio like normal, if applicable.

Once you have your packages created, you will want to cut them from K:\AosService\PackagesLocalDirectory and paste them into the Metadata folder we just created. In our example, it would be C:\Users\Admin4b2aaec26a\source\repos\NathanClouseAX\FOMultiPackageEasyWay\Metadata. We don't want any custom packages in K:\AosService\PackagesLocalDirectory. Only the Metadata folder will be under source control.

Next, add .gitignore file similar to how it is outlined above. An example is below:

# Ignore .vs
.vs

# But keep custom packages and models
!/metadata/test111
metadata/test111/bin/
metadata/test111/resources/
metadata/test111/XppMetadata/
metadata/test111/BPCheck.xml
metadata/test111/BuildModelResult.xml
metadata/test111/BuildModelResult.log
metadata/test111/BuildProjectResult.err.xml
metadata/test111/BuildProjectResult.xml
metadata/test111/CompileLabels.xml
metadata/test111/*.xref
metadata/test111/*.$usr

!.gitignore
!registerSymbolicLink.ps1
!unregisterSymbolicLink.ps1

Next, we'll be using scripts from this project: https://github.com/vxzry/d365fo-template. They are included in the example repo for this walkthrough. Run the script registerSymbolicLink.ps1 as an Administrator. Additionally, when adding new packages, you have to use the unregister script then run the register script again after moving new package(s). The unregister script is unregisterSymbolicLink.ps1.

Next, preview and commit all changes using Visual Studio. Any package level changes will require that the unregister then register scripts are used. Additionally, when changing branches, it would be a good idea to run the unregister script, change branch, then run the register script.

The Easy Way

Before we get underway, I want to emphasize this is a undocumented, unsupported option that is subject to change without notice. Additionally, it may break in future releases or have the setting get wiped during an upgrade. Furthermore, there is no specific reason to suspect that this will work forever. This work at the time of writing. All that being said, let's dig in.

Locate your web.config file. It is in K:\AosService\WebRoot for an Azure dev VM or C:\AosService\WebRoot for a local VHD. Open web.config as an administrator with your favorite text editor or using Visual Studio (save a copy before hand). Next, find key "Aos.MetadataDirectory". You can change the value for this key to be a different location where all of your custom packages will exist. For instance, C:\Users\Admin4b2aaec26a\source\repos\NathanClouseAX as <add key="Aos.MetadataDirectory" value="C:\Users\Admin4b2aaec26a\source\repos\NathanClouseAX" />.