chocolatey/choco-wiki

The content from this repository has been moved to https://github.com/chocolatey/docs. If you have found an issue, or want to submit a fix, then please open an issue, or a PR, on that repository.

THIS REPOSITORY IS DEPRECATED

See https://github.com/chocolatey/choco for further development

Chocolatey NuGet (like apt-get, but for Windows)

WEBSITE

Chocolatey.org

LICENSE

Apache 2.0 - see docs/legal (just LEGAL in the zip folder)

INFO

##Please see the wiki

SOURCE REQUIREMENTS

• .NET Framework 4.0
• PowerShell 2.0+

CREDITS

See docs/legal/CREDITS (just LEGAL/Credits in the zip folder)

choco-wiki's Issues

Package Internalizer page has invalid URLs

The Package Internalizer page has invalid URL's in the resources section for Getting Started With Chocolatey 4 Business & Jenkins CI and Using Chocolatey in Corporate Environments - Part 1.

Document Nexus 2 Repository Setup

Create documentation to setup Nexus for a hosted and caching repository.

Package Maintainer Handover page missing but linked to

There are links on Create Packages page and also on the Package Triage Process page to the Package Maintainer Handover page, however the page itself does not exist. Needs to be created.

Package triage; vendor documentation

I want to take over/help with package maintenance for my software

Based on the documentation, the site-admins should add the user to the package, no questions asked

I think the site-admins should verify that the sender is actually the vendor of the software.

Docs not clear about pushing beta software packages

I want to make a package for beta software (franz messenger). Unfortunately the documentation is not clear about what exactly I'd have to do to mark package versions as prerelease when pushing to the official choco-user repository.

set the beta as a prerelease when pushing the item to chocolatey.org (CreatePackages)

But in the docs about pushing packages I can't find anything that would explain how to do this with the command line.
Should I just extend the push command by -pre?

FEATURE REQUEST: Add documentation about Chocolatey Simple Server co-existance

(from chocolatey-community/simple-server#26)

The current "Setup Normally" documentation states "Disable or remove the Default website" It should be noted why; or more importantly how to make Chocolatey Simple Server coexist with pre-existing production web servers. I tested and now am using on a new IIS installation I'm sure a lot of people don't want to setup a new server just for Chocolatey Simple Server if they don't need to.

Make requirements more prominent

The requirements to install Chocolatey should be at or near the top of the document, not between information about installing behind a proxy and the mini-FAQ.

Also, the Requirements section states that "the installation will attempt to install .NET 4.0 if you do not have it installed", but it sure doesn't do that for me, and I don't see where install.ps1 is doing that. (Is it?) Instead, Chocolatey happily installs without error and then promptly fails when you try to use it.

If .NET is an up-front requirement that all users (even ones who will give up when they read "restricted TLS") will recognize, then there is no need for the install.ps1 to attempt to install it, but when the requirements are buried and an incorrect(?) claim is made, a lot of potential users will give up.

Describe What To Do When The Software A Package Represents Goes Away Or Is No Longer Available

Following the instructions of

When deprecating a Chocolatey Package, the following steps should be followed:

Create a new version of the deprecated Chocolatey Package.
Prepend [Deprecated] to the title of the package (e.g. <title="[Deprecated] Software Title" />
Update the package description: Why is the package being deprecated?
Add a dependency on the other package (if the package is being superseded).
Remove all files except the .nuspec from the Chocolatey Package.
Replace ... section in .nuspec with tag to prevent any file from being included with the package.
Remove the iconUrl.
Unlist all versions from the package gallery, except the final deprecated version. The final deprecated version is required so that there is an update path to the new package.
By following this process, any existing users who try to update the old package will automatically get the new package, as it will be installed as a dependency.

... when deprecating a package WITHOUT a replacement dependency results in:

Cannot create a package that has no dependencies nor content.

i.e. if there are no files and no dependency, you can't pack.

Suggestion:
Add to the docs: in the situation that the package is NOT being replaced by another package as a dependency, simply add chocolatey as a dependency to get around the problem, e.g. https://chocolatey.org/packages/ellp/86.20181230

If it's deemed this should be addressed in choco.exe, I'll be happy to create an issue there as well.

Variable reference is not valid. ':' was not followed by a valid variable name character.

Parameter password example is not valid and will throw the following:

Variable reference is not valid. ':' was not followed by a valid variable name character. Consider using ${} to delimit the name.

https://github.com/chocolatey/choco-wiki/search?utf8=%E2%9C%93&q=%24pp%5B%27Password%27%5D&type=

Document how to create a Chocolatey package as part of a GitHub release

Just as the title says, document the process you would use to create a Chocolatey package from a GitHub release. See this discussion

Provide FAQ about package size limit for Community packages

Followup for https://github.com/chocolatey/chocolatey.org/issues/424

Broken Link in the "Getting Started" page

What You Are Seeing?

Located in this Link: https://chocolatey.org/docs/getting-started#overriding-default-install-directory-or-other-advanced-install-concepts

There is a reference located here:
Portable Package - packages that use zip or just contain the runtime software. Usually these packages do not require administrative privileges to install or run. See https://github.com/chocolatey/choco/wiki/ChocolateyFAQs#portable-application-something-that-doesnt-require-a-system-install-to-use">

What is Expected?

I expected the link to work: https://github.com/chocolatey/choco/wiki/ChocolateyFAQs#portable-application-something-that-doesnt-require-a-system-install-to-use

How Did You Get This To Happen? (Steps to Reproduce)

By clicking on the link.

Workaround

copy the link and paste it in a new page.

Add Readme, license, etc

To explain what this repo is for, and how to go about contributing.

Update link to portable packages

The Non-Administrative install section mentions link to portable packages as

https://chocolatey.org/packages?q=id%3Aportable

This only covers packages with both installation and portable version. For example, the package tablacus is not covered. A better link would be

https://chocolatey.org/packages?q=id%3Aportable+tag%3Aportable

Issues with How-To-Parse-PackageParameters-Argument.md

I'm trying to create chocolatey packages that support package parameters. However, I'm struggling with the documentation at https://github.com/chocolatey/choco-wiki/blob/master/How-To-Parse-PackageParameters-Argument.md

1. The link in the first paragraph is dead https://github.com/chocolatey/choco-wiki/blob/master/CommandsInstall
2. The sentence NOTE: See #312 for Chocolatey v0.9.10 adding a helper to do the below with almost no boilerplate. made me think I'd find info in that issue about some newly developed helper functions making the below example more easier to achieve. After reading through it, it looks like a discussion about how to improve the situation (mentioning native powershell parameters), but it doesn't look like something actually improved. So why is it useful to read that issue if you want to understand how it currently works?
3. I'm trying to implement the given example into a new package. This is the content of my "chocolateyinstall.ps1" file http://pastebin.com/xJh8F0VV
   As you can see, I'm using exactly the same code, just searching for two custom parameters. However, when building the package and installing it via choco install packagename.nupkg -y -f -packageParameters '"/vst2:1 /vst3:0"', the lines 47 and 52 should trigger a warning and an error in the console but they don't. What am I doing wrong here?

I appreciate any help!

How to choco install, reboot, choco install?

Hi, I want to write a little script (one double klick) that automatically installs a predefined set of Software from Chocolatey but with some controlled reboots between the install commands to prevent interdependencies. How to accomplish that? :)

Example:

choco install ccleaner audacity firefox -y
reboot & wait 30 seconds after user logon
choco install thunderbird vlc gimp -y
reboot & wait 30 seconds after user logon
choco install app app app -y
reboot & wait 30 seconds after user logon

Stop recommending rawgit

Considering that rawgit will be shutting down next year, and since they no longer allows adding new urls (well, not trought the website).

I would suggest to either remove the suggestion on the CreatePackages, or change it to use a different provider (in this case, I suggest jsdelivr).

I'm willing to open a PR to change it to jsdelivr, if acceptable.

NOTE: Originally reported over at chocolatey/choco#1682

Add information about special files in the Chocolatey Package

Perhaps this should go on this page:

https://chocolatey.org/docs/create-packages

For example, placing a .skipAutoInstall file in the package will cause the auto uninstaller to be skipped.

Document how Chocolatey.org works with package icons

Add documentation around how the Chocolatey.org website works with the package icons.

Clarify text on packages being completely silent

• Make sure notes are clear packages should be completely silent as a rule and not as an exception
• If packages are not silent then this should be highlighted to the user
• This includes maintainer added pop-ups or interaction with the user

ENHANCEMENT: Additional Suggestions for Deprecation

A couple ideas up for discussion to improve standardization of deprecation:

1. Deprecated packages could have standard/recommended versioning. I suggest 99.99.99.99. Stealing from food industry slang, I also like the idea of "86ing" a package, so 86.86.86.86 would be a good alternate. If a date is deemed helpful to mix into the formula than either 99.99.99.yearmonthday or 86.86.86.yearmonthday.
2. Remove all tags and replace just with "deprecated"
3. Strip out bugTrackerUrl, docsUrl, licenseUrl, malingListUrl, projectSourceurl, releaseNotes, copyright, and requireLicenseAcceptance
4. Keep id, title, version, authors, owners, packageSourceUrl, summary, description, projectUrl, and tags

Not that I expect others to use it, but I personally enjoy throwing the graphic

into the description.

EDIT: This topic is really about RETIRING a package versus DEPRECATING a package. A new issue has been opened at #110 to address it more directly.

How-To-Deprecate-A-Chocolatey-Package requires tools dir with an empty file

The step:

Remove all files except the .nuspec from the Chocolatey Package.

Will result in package error if files section of .nuspec is pointing to tools directory. Removing the files section will pull in .git files. Updating files section exclude .git folder will not work either.

Based on @AdmiringWorm:

<files>
</files>

or

<files />

Will prevent the scm files from getting included in package.

Package Maintainer Handover page missing but linked to

The Package Maintainer Handover page is missing but is currently being linked to on the Package Triage Process page and the Create Packages page but the page being linked to does not exist and should be created.

Update Moderation Guidelines

Document moderation process and make it clearer both for moderators, maintainers and users.

See https://github.com/chocolatey/chocolatey.org/issues/575

Broken characters on shims website page

https://chocolatey.org/docs/features-shim

The above page is littered with broken characters, after some, but not all of the quotation marks. I can't immediately see anything in the source that would cause this.

`--install-directory` option does not work

On the doc page parameter passing is used with =
From the page: Just pass --install-directory=value along while on the gif there is no = sign.
I have tried to specify the install directory with both without any luck. I have also tried to use all the others like --installdir, every single time I got the following error.

PS D:\> choco install chocolatey --installdirectory 'myfolder'
Chocolatey v0.10.1
Installing the following packages:
chocolatey;--installdirectory;myfolder
By installing you accept licenses for the packages.
chocolatey v0.10.1 already installed.
 Use --force to reinstall, specify a version to install, or try upgrade.
--installdirectory not installed. The package was not found with the source(s) listed.
 If you specified a particular version and are receiving this message, it is possible that the package name exists but t
he version does not.
 Version: ""
 Source(s): "https://chocolatey.org/api/v2/"
myfolder not installed. The package was not found with the source(s) listed.
 If you specified a particular version and are receiving this message, it is possible that the package name exists but t
he version does not.
 Version: ""
 Source(s): "https://chocolatey.org/api/v2/"

Chocolatey installed 0/3 packages. 2 packages failed.
 See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).

Warnings:
 - chocolatey - chocolatey v0.10.1 already installed.
 Use --force to reinstall, specify a version to install, or try upgrade.

Failures
 - myfolder - myfolder not installed. The package was not found with the source(s) listed.
 If you specified a particular version and are receiving this message, it is possible that the package name exists but t
he version does not.
 Version: ""
 Source(s): "https://chocolatey.org/api/v2/"
 - --installdirectory - --installdirectory not installed. The package was not found with the source(s) listed.
 If you specified a particular version and are receiving this message, it is possible that the package name exists but t
he version does not.
 Version: ""
 Source(s): "https://chocolatey.org/api/v2/"
PS D:\>

external program failed (msbuild.exe)

I fetched latest choco, ran build.bat and got a build failure. See the log below.
My machine installed .net 4.5.1
Anyone can help?
Thanks in advance.

= = = = = = = = = = = = = = = = = = = =
[echo] Setting compile variables
[echo] Finding and restoring all packages (C:\chocolatey.0.9.9.12\choco\lib\NuGet\NuGet.exe restore 'C:\chocolatey.0.9.9.12\choco\src\chocolatey.sln')
[exec] Unable to find version '1.1.86' of package 'coveralls.io'.
[exec] C:\chocolatey.0.9.9.12\choco.build\compile.step(66,6):
[exec] External Program Failed: C:\chocolatey.0.9.9.12\choco\lib\NuGet\NuGet.exe (return code was 1)
[echo] Compiling C:\chocolatey.0.9.9.12\choco\src\chocolatey.sln.
[echo] Building on 4.0

        C:\chocolatey.0.9.9.12\choco\.build\compile.step(173,14):
        Failed to start MSBuild.
            C:\chocolatey.0.9.9.12\choco\.build\compile.step(173,14):
            External Program Failed: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\msbuild.exe (return code was 1)

Install Page Usability Suggestions

From a recent email:

I was getting a new machine setup and obviously went to chocolatey to accelerate the process.

Quick Usability Suggestions

1. Since the copy to clipboard icon is does not use the "cursor: pointer" css, it isn't obvious that it is clickable. I'd consider making the "copy command" text a javascript/link/action that also copies.
2. Instead of changing that, I think it would be even better if you copied the way that gist does their copy command. It is inline the with the text being copied, the icon is a little more obvious that it is a clipboard, it uses the hand pointer, the button changes color on hover, and there is a tooltip to tell you exactly what it is. Dare I say it is perfection in this regard. Since you're use the <pre> tag for your text, it looks like bootstrap's documentation has a nice working example too.

3. I had to spend 60 seconds searching for the exact ExecutionPolicy text I needed to use to get chocolatey to work. It would save everyone a little effort/grief if you made it a copy-able text snippit as well. I'm guessing you did it the way you did because there are security ramifications of setting it to unrestricted, but I think a simple warning note that they need to know what they're doing should suffice.

(doc) Versionning Recommendations could be clearer

Hi,
On this page:
https://chocolatey.org/docs/create-packages#versioning-recommendations

The versioning could be clearer.

1. It could contain a reference example to the code in the nuspec file, like:
   0.0.x
   It could also show bad examples with explanations like:
   Prod.123.x (bad because it's not only numbers)
   11.1 (allegedly bad because it's two digits, it should be only one)

2. It could be clear on what is accepted like only numbers, or something like:
   [0-9].[0-9].[0-9].[123456] (or whatever is correct). Also, having a clear sentence would be good, like only numbers separated by a dot, or something.

3. It could specify the maximum number of characters it can contains (apparently it's 20?)
   Ex, to avoid having 1.2.3.4567891011121314...

4. The explanation about segments could be consolidated, it's not always clear what is inside a segment (probably the steps above should help clarify).

Cheers!

Instructions for installing specific version are incorrect

On the site it says to install the specific version of a package the user should use -version <version number>
which results in this from the choco cmd line:

PS C:\WINDOWS\system32> cup phraseexpress -y -version 12.0.93
Parsing -version resulted in exception:
 Cannot bundle unregistered option '-e'.
Chocolatey v0.10.0 Business

the actual flag is --version (two dashes) which works as intended.

PS C:\WINDOWS\system32> cup phraseexpress -y --version 12.0.93
Chocolatey v0.10.0 Business
Upgrading the following packages:
phraseexpress
By upgrading you accept licenses for the packages.
phraseexpress v12.0.93 is the latest version available based on your source(s).

Anywhere we cite -version to be used with choco needs to be fixed.

ENHANCEMENT: Add how to RETIRE a package to the docs

When retiring a Chocolatey Package, the following steps should be followed:

• Create a new version of the retired Chocolatey Package.
• Prepend [Retired] to the title of the package (e.g. <title="[Retired] Software Title" />
• Change the package version to 99.99.99.99. Alternatively 86.86.86.8.6 or 86.86.86.yearmonthday. (discussion time)!
• Update the package description: Why is the package being retired?
• Create a chocolateyInstall.ps1 script that is either blank or simply has a Write-Host with the reason for retirement. (Necessary or you'll get a pack error of no content.)
• Delete all other files except chocolateyInstall.ps1 (and possibly a RETIRED.txt that is displayed via chocolateyInstall.ps1).
• Remove the iconUrl.
• Remove bugTrackerUrl, docsUrl, licenseUrl, malingListUrl, projectSourceurl, releaseNotes, copyright, and requireLicenseAcceptance.
• change tags to retired (e.g. < tags>retired< /tags>)
• If the distribution point (website) for the program files has ceased to exist and the program is no longer available, unlist all versions from the package gallery, except the final deprecated version. If the program is still available for download you can leave working package versions listed.
• By following this process, any existing users who try to update the old package will automatically get the new package and (hopefully) be informed of the retirement.

Personally, I prefer "[RETIRED]" over "[Retired]" as the status will be more noticeable.

An example retired package of mine:
https://chocolatey.org/packages/ellp/86.20181230

Update How To Setup Internal Package Repository page

The scripts and Jenkins code have evolved since the page was created and it should now be updated with those new versions.

choco

leave a commit

Document how to install the latest chocolatey beta

As an system engineer, it would be nice to install the latest chocolatey beta on a new machine. I would suggest to add this to the installation documentation, with an additional warning.

Document "bad" registry keys

https://groups.google.com/d/msgid/chocolatey/ed00a097-9c9c-4956-8c1e-44784938a68a%40googlegroups.com

Troubleshooting - Add fix for choco asking how to open nupkg

Add this to the Troubleshooting section of the wiki.

Document Artifactory Setup

Create documentation to setup Artifactory for a hosted and caching repository.

Document Extensions

chocolatey/choco#1011

PPP

Document internalizer process using CI/CD pipeline

Document how an organization would use the package internalizer with a CI/CD pipeline.

Document Azure DevOps Artifacts Repository Setup

Create documentation to setup an artifacts repository in Azure DevOps.

Needs chocolatey source for dependencies when testing locally

Here on Testing Package, under Creating Packages

https://github.com/chocolatey/choco/wiki/CreatePackages#testing-your-package

When suggesting using sources from local directory, it needs also to pass the chocolatey repo as a source, otherwise you won't be able to pull dependencies, and you will be met with a Unable to resolve dependency error instead.

By passing both the local dir and remote dir like -s “.,chocolatey” things will just work!

Add script to remediate registry.bad files

The troubleshooting section currently doesn't have any information inside of it for working with registry.bad errors.

Add info about installing GUI on chocolatey.org install page

It took me a while to even figure out there was a GUI option, since it's not mentioned anywhere on the installation page. While it was pointed out to me the GUI is mentioned on the main page, it's a single line buried in content mid-page, easy to miss. It would make sense to add info about installing the GUI to the install page.

I was asked to make a PR, but I've never done it and have no clue how, nor do I know if just modifying the html is enough, and I'd rather not screw it up. So instead, I've attached the suggested new page source here. See lines 109 and 131 for the changes. If you'd like me to do a PR, I will, just didn't want to cause more trouble than help.

Chocolatey Install.txt

Download fails when Downloadfile is called with 2 arguments due to Repo bug.

If the nuget repository returns multiple packages for IsLatestVersion the call to Downloadfile will fail.
This was triggered by a bug in Artifactory - however, it may be best to guard against such errors.

Exception calling "DownloadFile" with "2" argument(s): "The request was aborted: Could not create SSL/TLS secure channel."
At line:9 char:3

• $downloader.DownloadFile($url, $file)

$downloader = new-object System.Net.WebClient
$downloader.DownloadFile($url, $file)

Bug in Artifactory:
https://www.jfrog.com/jira/browse/RTFACT-15525

TOC links broken if heading contains slash (only on website)

Most Pages contain a table of content (TOC) with links to the subitems of the page.
If the subitem contains a slash / the link to this subitem is broken on the website (https://chocolatey.org/docs/).

Example https://chocolatey.org/docs/security

Security.md has a subitem named Servers / IP Addresses.
On Line 16 the TOC-link to this subitem is defined as:

- [Servers / IP Addresses](#servers--ip-addresses)

This is working for github and github-wiki markdown-preview/rendering, here a heading of foo / bar gets a generated id/anchor-tag of foo--bar.
But on the website a foo / bar heading gets an id/anchor-tag of foo-bar (only one minus).

There seems to be a little difference in auto-generating the anchor-tags of headings on the website which should be adjusted to the method that github is using.

---

Note: e.g. in Troubleshooting.md anchors that match the github-style had beed added by hand above the subitems-headings. Not sure if this is the preferred way to handle this.

Link overflow in website FAQ

https://chocolatey.org/docs/chocolatey-faqs

A link isn't closed properly at the start of the "What distinction does Chocolatey make between an installable and a portable application?".

It seems to be caused by a HTML anchor tag in the markdown - although I'm not sure why it's there, so didn't try to fix it!

<a name="AppVsTool" />
### What distinction does Chocolatey make between an installable and a portable application?
#### Installable application

Add Licensed Helper Function Reference

FOSS has a Chocolatey helpers page but while Chocolatey licensed has a link for a page, it doesn't actually exist (see chocolatey.org/docs and scroll down on the left hand side to the bottom of the Paid section).

The following functions are known about and should be added:

• Install-ChocolateyWindowsService
• Uninstall-ChocolateyWindowsService
• Start-ChocolateyWindowsService
• Stop-ChocolateyWindowsService

Weirdness while installing a package and a game on Steam at the same time

So I just installed Chocolately and I was installing my first package.
At the same time I was downloading something through Steam.

Document / Create PowerShell Script to Get Chocolatey.Server installed

It would be better to have the step by step and THEN a script that can be run to get Chocolatey.Server all set up correctly.