The issue is separating the artifacts that ship as part of the module from the artifacts that don't ship. The files under src are what get's published - for now. Eventually, if we have generated files i.e. signed scripts, module file catalog or platyPS generated help files, then the module publishing will be done from another, output dir after the module is built.

The preferred mechanism for using the module is to install it from the PowerShell Gallery via Install-Module. If you are developing for posh-git, then import the module by path. This is what I put in my profile:

Import-Module ~\GitHub\dahlbyk\Posh-Git\src\posh-git.psd1

It's worth noting that I ran into this here, and at the time it seemed easiest to just work around it. But then I hit it again here while publishing to the PowerShell Gallery.

As @rkeithhill notes, you should still be able to Import-Module ~\Documents\WindowsPowerShell\Modules\Posh-Git\src\posh-git.psd1 directly, but that rather defeats the point of living in Modules.

Even if we do get to the point where we need an explicit build step, I don't see much harm in moving everything in src/ another level deeper into src/posh-git/ to align with how PowerShell thinks of modules. And now that I think about it, separating out another module in src/posh-ssh-agent/ could be a reasonable step toward #338.

@rkeithhill talk me out of this?

Adding another level under src while we don't have a build process is fine. I'm not going to talk you out of it. :-)

Other PowerShell module repos that do have a build process, build to either <repoRoot>/out/<module-name>/<version> or <repoRoot>/<version> (where repoRoot is typically the module name).

As a community starting to work on standardizing the build process for PowerShell modules, we're trying to figure out what's best. But I do know that once you go down the signed script path, you do not want to be signing (modifying) the original (src) scripts. Likewise, you don't really want to be generating files into src or the root of the repo.

You could I suppose gitignore those files so accidental commit doesn't become an issue but then cleaning a build gets a bit messier. Better to have built output in its own dir so that cleaning becomes a simple dir wipe.

@bgshacklett before I make this change, can you confirm that moving everything under src/ into src/posh-git/ fixes your use case?

@dahlbyk I checked out the v0.7.1 tag, then manually moved the contents of src/ into src/posh-git/ This creates some very interesting behavior. Doing so made the module visible to PowerShell (Get-Module posh-git -ListAvailable), but Import-Module still fails. That said, if I run a command from the posh-git module, the module is loaded. Perhaps there is a change I need to make in my PowerShell profile to allow this to work? Given this behavior, adding Start-SshAgent to my profile should be sufficient to get things back to where they were prior to 0.7.1 with this directory change, so I'll test it for a while and see if I run into any issues.

I must admit that I don't understand how the module is being found at all. I was under the impression that a module folder must exist directly below one of the locations in $env:PSModulePath; I was not aware that PowerShell would recurse into the path to look for modules; it's always nice to learn something new.

Shell output:

PS ~> mv ~\Documents\WindowsPowerShell\Modules\posh-git\src\* ~\Documents\WindowsPowerShell\Modules\posh-git\src\posh-git\
PS ~> powershell
Windows PowerShell
Copyright (C) 2016 Microsoft Corporation. All rights reserved.

PS ~> get-module posh-git
PS ~> Import-Module posh-git # Note that Tab Completion is successful
Import-Module : The specified module 'posh-git' was not loaded because no
valid module file was found in any module directory.
At line:1 char:1
+ Import-Module posh-git
+ ~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceUnavailable: (posh-git:String) [Import-M
   odule], FileNotFoundException
    + FullyQualifiedErrorId : Modules_ModuleNotFound,Microsoft.PowerShell.Comm
   ands.ImportModuleCommand


PS ~> Get-Module posh-git -ListAvailable


    Directory:
    [redacted]\Documents\WindowsPowerShell\Modules\posh-git\src


ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Script     0.7.1      posh-git                            {Invoke-NullCoales...

PS ~> Get-SshAgent
14924

# a change in the prompt indicates that posh-git has been loaded.
~> Get-Module posh-git

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Script     0.7.1      posh-git                            {Add-PoshGitToProf...

~>

Doing so made the module visible to PowerShell (Get-Module posh-git -ListAvailable), but Import-Module still fails.

This kind of thing is maddening. If the file is valid, why does its parent path matter!

To confirm, posh-git is not found by Get-Module if it's in src/, only if it's in src/posh-git/? The other option for us would be to replace src/ with posh-git/, which I assume will work.

Sorry I never replied. I suspect my browser must have crashed and I lost track of what I was working on at the time. I'm seeing the same behavior regardless of whether the manifest is at src/ src/posh-git/ or posh-git/ which is quite troubling. I think I'm going to come up with a simple test case and post an issue on the PowerShell repo.

At any rate, moving the module to posh-git does allow it to be imported automatically when an exported function is called, so that's a start, but I agree that it's quite frustrating behavior.

PowerShelll looks under a Modules dir for either <module-name>\<module-name>.psm1|psd1 or <module-name>\<version>\<module-name>.psm1|.psd1. So creating a posh-git under src isn't going to work in this scenario. What we "could" do is create a simple build.ps1 script that copies the contents of src into a directory named by the current version e.g. 0.7.1. So you wind up with posh-git\0.7.1 and that will load correctly. We'd have to add a .gitignore entry that was a regex equivalent of \d\.\d\.\d.

Unless we need to compile something, a build process doesn't seem like it should be necessary to run a fresh clone.

So if I'm understanding this correctly, the only way to reasonably fix the posh-git-as-submodule scenario (assuming the submodule folder is named posh-git/) is to move the .psm1/.psd1 up into the root of the project?

Actually a build process doesn't have to be that complicated and can be handy especially for publishing. For instance, we can add optional params to the build to allow the prerelease value to be tweaked in the PSD1 file. Other than that, the build could simply be a copy of the src contents into a folder named after the version. This also has the benefit of allowing you to have both a posh-git\0.7.2 folder and a posh-git\1.0.0 folder.

To clarify, automating the release process would be rad. But it doesn't seem like it should be necessary to build before Install-Module works from a fresh clone.

You mean Import-Module? That always works from a fresh clone - simply run Import-Module ~/github/posh-git/src/posh-git.psd1 - that is, import by path.

If you want to import by name then you already have to do something - you have to modify $env:PSModulePath and if you do that via the control panel applet, you'll have to restart PowerShell to get the new value. In general, I don't recommend folks muck with their PSModulePath. You're asking for trouble if you screw it up.

Yeah, sorry, I mean Import-Module posh-git working if the repo is cloned to a path under $env:PSModulePath. You can certainly import a direct path, which is what Add-PoshGitToProfile does if src is in the path from a clone.

Not a deal-breaker, but if we can trivially fix it (e.g. move the module definition up into the root) without breaking anything else...