Skip to content

evandrocoan/channelmanager

BranchesTags

Repository files navigation

Channel Manager

The plugin channel_manager.py creates the files channel.json and repository.json based on the .gitmodules file on the Sublime Text Data folder (the folder at Packages/../). To call it, you can open the command palette and type YourChannelName: Generate Channel File. See the following threads for more information about the Package Control channel and repository files:

  1. https://packagecontrol.io/docs/dependencies DOCS - Dependencies
  2. https://packagecontrol.io/docs/channels_and_repositories Channels and Repositories
  3. wbond/package_control#1089 Package dependencies (install dependent sublime packages)
  4. https://forum.sublimetext.com/t/dependencies-in-package-control-3/14646 Dependencies in Package Control 3
  5. https://forum.sublimetext.com/t/modules-dependencies-best-practices/21037 Modules + Dependencies : Best Practices?
  6. wbond/package_control#1070 [Meta] What to do when a dependency update includes breaking changes?

Table of Contents

Introduction Go to Top

channelmanager is dependency which manages the packages installed by git as submodules. It allows to create the channel files required by Package Control to list and install packages. It is Currently implemented two different bundle of package bounded by .gitmodules files. The StudioChannel and the AmxxChannel.

  1. StudioChannel This is one of the first channels implemented using the channelmanager. It contains about 100 packages for the stable version and 150 for the development version. It has a custom installation wizard to guide you through the installation steps and therefore call the channelmanager's installer passing the required configurations for the SublimeStudio.

  2. AmxxChannel This is a smaller channel of packages with about 20 packages focused on just for programming for AMX Mod X Pawn language at AmxxSimpleIDE

The channel creation is based on the existence of a .gitmodules file on the root of your Sublime Text Data folder. For example, at the portable version of Sublime Text the folder structure would look like this:

$ tree
.
├── .git
│   ├── COMMIT_EDITMSG
|   ...
├── .gitmodules
├── Cache
│   ├── ActionScript
│   │   └── ActionScript.sublime-syntax.cache
|   ...
├── Installed Packages
│   ├── 0_package_control_loader.sublime-package
│   ├── Amxx Pawn.sublime-package
│   ...
├── KEEPME
|   ...
└── Packages
    ├── amxmodx
    │   ├── amxx.sublime-settings
    ...

The contents of the file .gitmodules follow the requirements by .gitmodules, but also including new keys used to generate the channel files. Currently there are implemented the following keys:

[submodule "Packages/Notepad++ Color Scheme"]
    path = Packages/Notepad++ Color Scheme
    url = https://github.com/evandrocoan/SublimeNotepadPlusPlusTheme
    upstream =
    branches = master->master

The upstream can be empty or not present if you would like to. It is used to set your repository upstream when the project is a fork of some another project. For example, let us suppose you liked the project https://github.com/evandrocoan/SublimeNotepadPlusPlusTheme and created a fork of it on Github. Now, instead of installing the original package from evandrocoan, you installed your fork, from your address https://github.com/your_user_name/SublimeNotepadPlusPlusTheme, then you would set the upstream key pointing to the original repository and the url key for your fork of it.

The keys upstream and branches are used to create create pull-requests from the upstream remotes with the Python Module githubpullrequests, and by commands like Pull & Rebase all Upstreams (see section #commands-go-to-top).

Tags Management Go to Top

You can create specific settings for each repository on the file settings.json, which should be put on the aimed repository root directory of repository. See this settings.json file example, on the root of Notepad++ Color Scheme package:

{
    "tags":
    [
        "3144"
    ]
}

The tags is a list of remote tags and the version of Sublime they are aimed to be used. For example, tags = 3143, 3147 indicates the repository Notepad++ Color Scheme has the following git tags called 3143 and 3147.

Note, if some value of the tag option is not an integer, the download/url link will point to that name. For example, if you set tag = master, the download link will always point the master branch. This is useful when you are want a package to always be downloaded from the latest version on the master branch.

Settings tags like 3143 is useful when a package has ceased working for old build of Sublime Text. For example, on Sublime Text development build 3147, the package Notepad++ Color Scheme stopped working completely (CoreIssue$1983) however the fix for build 3147 also broke completely the package for Sublime Text stable build 3143. Hence, we must to create a tag which targets the last commit which is working for build 3143. Moreover, when some user using the stable build 3143 installs the Notepad++ Color Scheme, they must install the one from the tag 3143, and not the one from the master branch, which has the latest fixes for build development build 3144 or newer. Stills also to do automatic tagging of the latest release package is working for Sublime Text as the tag 3143 just mentioned, however this seems not much required to be done as should there be only a few exceptions for when a packages stops working for some build of Sublime Text.

Currently the channel generation is limited to setting the download link to a tag pointing to the the repository master branch. For now, it is disabled all tag prefixes, i.e., tags which are not strictly "0.0.0", because we cannot handle repositories which have a tag prefix for each platforms as Linux and Windows. Then we create a unified tag which is based on the current master branch. Despite it was implemented the checking for each submodule for the latest tag available, then properly setting the download URL pointing to the last tag, based on the latest commit date. Currently it is only partially implemented the tag management. It is required to also implement on the .gitmodules file, the tag_prefix field to select which is the tag prefix, and for which platform.

It would be useful for tagging a large set of packages which can be considered stable. This approach should be much batter than the current one where the user always download the current version available at the master branch when the user installed the package. Such approach is not very welcomed because would allow several clients to be using different versions of the package while all of them think they are using the latest version available at the moment, however just the most recent installations would be using the lasted version, whereas the other installations would be using some older version.

Submodules Manager Go to Top

The plugin submodules_manager.py run several operations based on the .gitmodules file on the Sublime Text Data folder (the folder at Packages/../) and Backstroke.gitmodules file on the Sublime Text Data folder (the folder at Packages/../Local). However, still to do a implementation of a configuration which will allow you to change the locations of these files by settings files. So you can put them where you please most. Here is a sample of the structure of both files:

.gitmodules

[submodule "Packages/Better CoffeeScript"]
    path = Packages/Better CoffeeScript
    url = https://github.com/evandrocoan/sublime-better-coffeescript
    upstream = https://github.com/aponxi/sublime-better-coffeescript
    branches = master->master
[submodule "Packages/BufferScroll"]
    path = Packages/BufferScroll
    url = https://github.com/evandrocoan/BufferScroll
    upstream = https://github.com/titoBouzout/BufferScroll
    branches = master->master

Backstroke.gitmodules

[submodule "Packages"]
    url = https://github.com/evandrocoan/Packages
    upstream = https://github.com/sublimehq/Packages
    branches = master_upstream_branch->master_fork_branch

[submodule "Packages/ANSIescape"]
    url = https://github.com/evandrocoan/SublimeANSI
    upstream = https://github.com/aziz/SublimeANSI
    branches = master_upstream_branch->master_fork_branch

Hence, if you would like to receive updates from the https://github.com/evandrocoan/SublimeNotepadPlusPlusTheme upstream, you can set the key upstream pointing to the upstream of the original package at https://github.com/evandrocoan/SublimeNotepadPlusPlusTheme. Therefore, your settings file would look like:

[submodule "Packages/Notepad++ Color Scheme"]
    path = Packages/Notepad++ Color Scheme
    url = https://github.com/your_user_name/SublimeNotepadPlusPlusTheme
    upstream = https://github.com/evandrocoan/SublimeNotepadPlusPlusTheme
    branches = master->master

Sadly, this feature is not implemented yet. However, the upstream key is used by the plugin submodules_manager.py, with the command line argument -f. The submodules_manager.py provides some commands which are not available from Sublime Text due they being too long to run. Moreover, it is proper to use a dedicated shell for them. You can see the available options for the submodules_manager.py by running it:

$ python3 submodules_manager.py
[submodules_manager.py] 14:44:07  454080    2707 Entering on main(0) None
[submodules_manager.py] 14:44:07  454322     242 ( print_command_line_arguments ) len(sys.argv): 1
[submodules_manager.py] 14:44:07  454403      81 ( print_command_line_arguments ) arg: submodules_manager.py
usage: submodules_manager.py [-h] [-a] [-b] [-f] [-p] [-t]

Update Sublime Text Channel

optional arguments:
  -h, --help        show this help message and exit
  -a, --all         Generate all assets
  -b, --backstroke  Check all backstroke registered repositories updates with
                    their upstream. The backstroke URLs are now in a separate
                    file on: Local/Backstroke.gitmodules
  -f, --find-forks  Find all repositories forks, fetch their branches and
                    clean the duplicated branches. The upstream data in on the
                    `.gitmodules` file on: Sublime Text `Data` folder
  -p, --pull        Perform a git pull from the remote repositories
  -t, --push-tags   Perform a git push for all submodules tags to their
                    respective remote repository

By just calling the submodules_manager.py with the --find-forks argument, it will run automatically through all your git submodules listed on the file .gitmodules. But still to do a argument to be passed to the command to allow select one specific repository to run the command, instead of running it right away through all your installed repositories, thing which can take several hours.

The find_forks command call the python package find_forks which finds all forks of user/repository on github and add it as git remote to your local cloned repository. It is useful to find interesting commits of old repository with many updated forks, fresh repository with many forks that original author doesn't want or doesn't have time to merge.

Channel Installer/uninstaller Go to Top

The plugins channel_installer.py/channel_uninstaller.py performs the installation and uninstallation of the of all the channel packages by the Package Control when installing the Stable Version, or by git when installing the Development Version of the channel.

Currently the installer has some hard coded configurations which are implemented directly on the code. But futurely they should be moved on from the dependency channelmanager to the package which actually is using the dependency channelmanager to do the channel administration.

How to Build a Channel Go to Top

The original purpose of the channel is to be small, something like just a few hundred of packages. However, you can scale up, if you do not actually install everything as a git submodule. The channel can in also be installed at once, including all its packages. That means, if you have big channel like with 1000 packages, you can call the channel installer, and those 1000 packages are going to be installed in your Sublime Text.

The installer provides two installation alternatives, the Development Version and the Stable Version. By installing the Stable Version, all the packages in your channel are going to be installed, except the one listed in the PACKAGES_TO_IGNORE_ON_DEVELOPMENT setting. Then, for example, you can have as much as 1000 packages in your channel, but list 960 of them by their names at the PACKAGES_TO_IGNORE_ON_DEVELOPMENT setting. Hence only 40 packages are going to be installed when the channel installer run.

However, this is only true if the user is installing the Stable Version of the channel. The Development Version will clone by git all the 1000 packages and then add the 960 packages listed on the PACKAGES_TO_IGNORE_ON_DEVELOPMENT file to the user ignored_packages settings.

This was designed like that because the original goal of this is to be just a small channel for a few packages you always install, or are developing. However, if you wish to scale up building very large channels, you can just decide not to use the channel installer to install the channel packages and just pick they one by one, as you usually do with the default Package Control channel.

  1. Install Sublime Text portable version, you can download it at: https://www.sublimetext.com/3

  2. Open your Sublime Text loose Packages folder by going the menu Preferences -> Browse Packages... Now open a command line you the folder which just opened:

    Linux Opening Linux Command Line


    Windows Opening Windows Command Line


  3. Use your command line and go to the parent folder of your Packages folder, and create a git repository, which will hold/tie together all the packages available in you channel. For example:

    cd ..
git init
printf "# Main Repository\n\nFor my packages' channel." > README.md
git add README.md
git commit -m "Added README.md"
git remote add origin https://github.com/your_user_name/main_repository

  4. Now your Main Repository is set up, use the same command line to install the Packages you want to add to your channel and adding them as git submodules to the main repository. For example:

    git clone --recursive https://github.com/jisaacks/GitGutter "Packages/GitGutter"
git submodule add -- https://github.com/jisaacks/GitGutter "Packages/GitGutter"
git commit -m "Added the first package to my channel."

  5. Now your .gitmodules file was created by git. It should look like this:

    [submodule "Packages/GitGutter"]
    path = Packages/GitGutter
    url = https://github.com/jisaacks/GitGutter

    With this setup, you can customize your file adding the required information to build up the channel. Let us start by adding the keys for the channelmanager installer & uninstaller:

    [submodule "Packages/GitGutter"]
    path = Packages/GitGutter
    url = https://github.com/jisaacks/GitGutter

[submodule "Packages/channelmanager"]
    path = Packages/channelmanager
    url = https://github.com/evandrocoan/SublimeChannelManager
    upstream =

    The packages channelmanager is responsible for generating the channel files, installing and uninstalling them. As it is set on the .gitmodules file, You can read more about the dependency load order on Package Control, Docs: Dependencies

    As it is a dependency, if you just skip it, i.e., not add this entry to your .gitmodules file as Package Control will fail to install it when you requires it on the actual package which provides the commands, because:

    1. The installation could just not work, if the dependency channelmanager and debugtools are not available on the Package Control default channel.
    2. You cannot use all the features available because currently it is dependent on git submodules and Package Control cannot clone the submodules together yet. Therefore, cannot use the features dependent on the submodules as the find_forks command.

    But also, you can add channelmanager to enforce the policy of development, adding channelmanager here allow you to easily edit its code, fix bugs or improve whatever it is doing as you already have a full git repository at hand, you just need to change the remote to a new repository or for a fork of yours at GitHub.

    Therefore as you may notice, was skipped the addition of the dependency debugtools, as it is not dependent on git submodules and there is not much room for improvement or changes on it. However, if you like you can also add it as a package. You just need to add the following entry to your .gitmodules:

    [submodule "Packages/GitGutter"]
    path = Packages/GitGutter
    url = https://github.com/jisaacks/GitGutter

[submodule "Packages/channelmanager"]
    path = Packages/channelmanager
    url = https://github.com/evandrocoan/SublimeChannelManager
    upstream =

[submodule "Packages/debugtools"]
    path = Packages/debugtools
    url = https://github.com/evandrocoan/debugtools
    upstream =

  6. Now you added the basics, you may notice they were not added as git submodules by the commands git clone --recursive repo_url and git submodule add -- repo_url "Packages/package_name". Moreover you can or cannot do so if you like. The channelmanager only requires to the file .gitmodules to exists in the pre-configured location, which we are about do to. Other than that, you do not need to have a parent repository which holds a valid .gitmodules file by your git client.

    However, it is required for some commands available to work properly as the command Pull & Rebase all Packages. Beyond that advised and nice to have a parent repository which validly by git ties together all the packages, because you can in only open place manage all your packages and easily create commits, pulls, pushes, etc. On this picture we can see some of this integration by a git client Graphic Interface:

    git client Graphic Interface

    To create the channel you need the configuration loader for the dependency channelmanager. This configuration loader would be a Sublime Text Package which requires the channelmanager as a dependency and call its installer, uninstaller and commands available passing the configuration required by the channelmanager dependency to run its operations.

    First of all let us create the folder for our new channel, you can name it as you like as long as there is no other package installed with the same. Assuming you still have the command line opened on the folder we were before, you can create the folder for the your channel:

    mkdir -p "Packages/MyBrandNewChannel"
cd "Packages/MyBrandNewChannel"
git init

    But without forgetting, we need to create an entry for the channel on our .gitmodules file. At the end of it all, the .gitmodules would look like this for the channel named MyBrandNewChannel:

    [submodule "Packages/GitGutter"]
    path = Packages/GitGutter
    url = https://github.com/jisaacks/GitGutter

[submodule "Packages/channelmanager"]
    path = Packages/channelmanager
    url = https://github.com/evandrocoan/SublimeChannelManager
    upstream =

[submodule "Packages/debugtools"]
    path = Packages/debugtools
    url = https://github.com/evandrocoan/debugtools
    upstream =

[submodule "Packages/MyBrandNewChannel"]
    path = Packages/MyBrandNewChannel
    url = https://github.com/your_user_name/MyBrandNewChannel
    upstream =
    • Note: Due Package Control currently not accept dependencies requiring dependencies, we also need to add the channelmanager dependencies to the MyBrandNewChannel dependencies list:

    dependencies.json

    {
    "windows": {
        ">3000": [
            "python-pywin32",
            "portalockerfile",
            "concurrentloghandler",
            "debugtools"
        ]
    },
    "*": {
        "*": [
            "portalockerfile",
            "concurrentloghandler",
            "debugtools"
        ]
    }
}

    On this case, we added the dependency debugtools to the MyBrandNewChannel dependencies list, as channelmanager requires the debugtools as dependency. See the following issue for details about when this should be correctly supported by Package Control:

    1. package_control#1300 If a dependency has a dependency, its dependencies are not installed
    • Note: We need to add the entry tag = master on the MyBrandNewChannel repository entry due the channelmanager installer get the packages names list to install from the current installed version of MyBrandNewChannel repository. Then if we only download the latest tag for MyBrandNewChannel, we will miss installing the latest added packages, unless the MyBrandNewChannel is re-tagged right after the creation of the channel.json and repository.json files.

  7. Now on this new package called Packages/MyBrandNewChannel, you need to create the plugin to call the channelmanager passing the required configurations. In the following we may see a full example configuration file, you can save it inside the folder Packages/MyBrandNewChannel with the name you like most as settings.py:

    import os

# from debug_tools.third_part import print_all_variables_for_debugging
# if 'g_channelSettings' in globals(): print_all_variables_for_debugging( g_channelSettings )
# import sublime_plugin; sublime_plugin.reload_plugin( "channel_manager.channel_utilities" )

from debug_tools.third_part import clean_urljoin
from channel_manager.channel_utilities import run_channel_setup

CURRENT_PACKAGE_FILE   = os.path.dirname( os.path.realpath( __file__ ) )
PACKAGE_ROOT_DIRECTORY = CURRENT_PACKAGE_FILE.replace( ".sublime-package", "" )
CURRENT_PACKAGE_NAME   = os.path.basename( PACKAGE_ROOT_DIRECTORY )

def plugin_loaded():
    global g_channelSettings
    CHANNEL_RAW_URL = "https://raw.githubusercontent.com/your_user_name/MyBrandNewChannel/master/"

    g_channelSettings = {}
    g_channelSettings['CHANNEL_ROOT_URL']    = "https://github.com/your_user_name/MyParentRepository"
    g_channelSettings['DEFAULT_CHANNEL_URL'] = "https://packagecontrol.io/channel_v3.json"

    g_channelSettings['CHANNEL_FILE_URL']  = clean_urljoin( CHANNEL_RAW_URL, "channel.json" )
    g_channelSettings['CHANNEL_FILE_PATH'] = os.path.join( PACKAGE_ROOT_DIRECTORY, "channel.json" )

    g_channelSettings['CHANNEL_REPOSITORY_URL']  = clean_urljoin( CHANNEL_RAW_URL, "repository.json" )
    g_channelSettings['CHANNEL_REPOSITORY_FILE'] = os.path.join( PACKAGE_ROOT_DIRECTORY, "repository.json" )

    g_channelSettings['PACKAGES_TO_INSTALL_FIRST'] = \
    [
        "My First Package",
        "My Second Package",
        "My Third Package",
    ]

    g_channelSettings['PACKAGES_TO_INSTALL_LAST'] = \
    [
        "My Package Penultimate Package",
        "My Package Penult Package",
        "My Package Last Package",
    ]

    g_channelSettings['FORBIDDEN_PACKAGES'] = \
    [
        "My First Forbidden Package",
        "My Second Forbidden Package",
    ]

    g_channelSettings['PACKAGES_TO_NOT_INSTALL_STABLE'] = \
    [
        "My First Package to not Install",
        "My Second Package to not Install",
    ]

    g_channelSettings['PACKAGES_TO_NOT_INSTALL_DEVELOPMENT'] = \
    [
        "My First Package to not Install",
        "My Second Package to not Install",
    ]

    g_channelSettings['PACKAGES_TO_INSTALL_EXCLUSIVELY'] = \
    [
    ]

    g_channelSettings['PACKAGES_TO_IGNORE_ON_DEVELOPMENT'] = \
    [
        "My First Package to ignore",
        "My Second Package to ignore",
    ]

    g_channelSettings['CHANNEL_VERSIONS_DESCRIPTIONS'] = """\
        There are two versions of the channel. Each one of them has its proper usage depending on
        your plans. The Stable Version is the most tested and trusted set of packages to be
        installed. It contains all the packages which can be actively enabled and used on daily
        basis usage and it requires the latest Stable Build of Sublime Text available, as builds
        3126 and 3143.

        The Development Version has the same packages as the Stable Version, however it also
        installs candidate packages to the Stable Version, i.e., packages which are not thoroughly
        tested. Some of them are expected to have serious bugs as crash your Sublime Text,
        significantly slow down the Sublime Text performance, i.e., create great problems. Due this,
        these extra packages are by default added to your `ignored_packages` settings. You should
        only enable them when you are attempting to fix their problems or test them.

        For both Stable and Development versions, your Sublime Text's Package Control will be
        uninstalled and replaced by the its forked version called `PackagesManager`. Now on, you
        should look for the package `PackagesManager` to install and uninstalling packages. The
        Stable Version installs all packages by PackagesManager as they normally are installed by
        the Sublime Text's Package Control. Therefore they require smaller amount of space in your
        file system. It should be about 60MB of data, on the last time checked.

        Now the Development Version installs all your packages by `git`, therefore you need to have
        git installed in your system in order to install the development Version. Also due this, the
        Development Version requires much more file system space. The last time checked it required
        about 600MB of free space. Notice also, the Development Version requires the latest
        Development Build of Sublime Text available, as builds 3141 and 3147.
        """

    run_channel_setup( g_channelSettings, CURRENT_PACKAGE_FILE )
    1. PACKAGE_ROOT_DIRECTORY/CURRENT_PACKAGE_NAME
      • Infer the correct package name and the root directory of the channel
    2. plugin_loaded()
      • We can only load the information when the Sublime Text API is available due the use of the get_main_directory() which requires it.
    3. run_channel_setup()
      • Generate the files Main.sublime-menu, Default.sublime-commands and commands.py files
    4. CHANNEL_ROOT_DIRECTORY
      • The directory where the Sublime Text loose Packages directory IS ON/IN/INSIDE
    5. g_channelSettings
      • Hold all the information for this channel, which will be used to install this channel
    6. CHANNEL_PACKAGE_NAME
      • The name of your channel
    7. TEMPORARY_FOLDER_TO_USE
      • The temporary folder to download the main repository when installing the development version
    8. USER_FOLDER_PATH
      • A direct Path to the User settings folder
    9. CHANNEL_INSTALLATION_DETAILS
      • A direct Path to the channel installation details saved after the completion of installation of the channel
    10. DEFAULT_CHANNEL_URL
      • The default Package Control channel full URL address
    11. CHANNEL_RAW_URL
      • The URL of the directory where the files channel.json and repository.json are hosted
    12. CHANNEL_ROOT_URL/CHANNEL_ROOT_DIRECTORY
      • A direct URL/Path to the main to the repository where there is the .gitmodules
    13. CHANNEL_FILE_URL/CHANNEL_FILE_PATH
      • A direct URL/Path to the Repository File channel.json to use when installing the stable/development version
    14. CHANNEL_REPOSITORY_URL/CHANNEL_REPOSITORY_FILE
      • A direct URL/Path to the Repository File repository.json to use when installing the stable/development version
    15. USER_SETTINGS_FILE
      • The default user preferences file
    16. PACKAGES_TO_INSTALL_FIRST/PACKAGES_TO_INSTALL_LAST
      • You can specify for some packages to be popped out from the list and being installed by first/last in the following order presented.
    17. FORBIDDEN_PACKAGES
      • Packages which are not allowed to be selected by the user while choosing the packages to not be installed. Useful for packages which are required for the channel maintainability.
    18. PACKAGES_TO_NOT_INSTALL_STABLE
      • Packages which you do want to install when reading the .gitmodules packages list (stable)
    19. PACKAGES_TO_NOT_INSTALL_DEVELOPMENT
      • Packages which you do want to install when reading the .gitmodules packages list (development)
    20. PACKAGES_TO_IGNORE_ON_DEVELOPMENT
      • Packages which must not be installed on the stable version and must be disabled by default on the development version, i.e., added to the ignored_packages list setting.
    21. PACKAGES_TO_INSTALL_EXCLUSIVELY
      • If this list variable has length greater than 0, it will only add the packages which are listed on it when installing the channel. This is useful to maintain two or more channels within the same channel.json repository file.

If you want to get more elaborated with the installation process, you can see the StudioChannel and the AmxxChannel files as example. The AmxxChannel implementation is similar to the one presented just above. However, the StudioChannel is pretty much different. It employs use concept of Installation Wizard, presenting a survey of the contents being installed.

How to Use a Channel Go to Top

The Channel is usable by two ways, the first is to create a big channel as Package Control with like 2000 packages or much more, listed by the .gitmodules file. The second is by creating a small channel of packages with with just a few packages as about 10 or 100 packages.

The first usage is when you intend just create big list of packages for sharing like Package Control does. This would not allow anyone to attempt to use the channel installer, as it would install all the packages, which is a lot of them. However this has the downside of requiring all the packages to be cloned on your computer for generating the channel.json and repository.json file.

It is made like to so it is not required to have an GitHub API token access, as you can only perform 60 access per hour without one. Now instead of pulling GitHub server with requests for the packages data, we just access it by the command line interface as the package is cloned locally in your computer.

The second usage is when you intend to share with our work colleagues or friends, a bundled set of packages for Sublime Text. You can just pass the channel URL for them to add it to the Package Control channel's list, then they can install your channel and run its installer.

When the user finish the installation of the channel, the channelmanager dependency will show up a message dialog informing whether the installation was successful or not:

Successful Installation Message Dialog

Multiple Channels Installation Go to Top

You can install as many Stable Versions of the channels as you want to. However, the Development Version due its nature can only have one installed. If you attempt to install a second Development Version, the channelmanager will not let you. But it stills installing the packages which are not present on the current installed channel.

Despite you cannot install multiple Development Versions, you can still install one Development Version and as much Stable Versions you would like to. Nevertheless, the packages which each channel have in common, are going to overridden accordingly to the channels installation order. For example, if you installed a Channel A, then another Channel B, and both channels have in common the same Package C, the implementation of the Package C, by the Channel A, will be overridden by the implementation of the Channel B, i.e., they are overridden accordingly to the order of the most recent channel installation.

It is also implemented on the channelmanager dependency, an short installation wizard which should allow you to choose which packages of Channel you do not want to install. Therefore you could select which of these packages you would like to install over the packages you already has installed. However, this list limited by the setting FORBIDDEN_PACKAGES which specify packages which must be installed. If the user do not agree with installing these packages, then he cannot install the channel.

Commands Go to Top

It provides the following commands on command palette. Note these commands only works if you installed the Development Version of the channel:

  1. YourChannelName: Generate Channel File Creates the files channel.json, repositories.json. The file channel.json and repositories.json are the same file as the Package Control's channel_v3.json file. You can read more about them at Package Control, Docs: Channels and Repositories

  2. YourChannelName: Select Packages to Update Git Tag Before running this command, you must have already called Generate Channel File to create the channel files, as this commands just load those files and create a git tag as performed on the command Generate Channel File, however the tag is only created if it does not already exists a tag for the current/latest commit. Also, the tag is immediately pushed to origin.

  3. YourChannelName: Update All Packages Git Tag Similar to the last command Select Package to Update Git Tag, but it create git tags for each repository on based on the date of the last commit. If there is no git tags, a first tag is created as 1.0.0. If already there are git tags, its patch component (or major.minor.patch) is incremented in one.

  4. YourChannelName: Cancel Current Operation If there is some operation currently running, it will be cancelled some time after this command is called. Please, do not call cancel and immediately call some other operation. Wait a a few seconds until the operation stops.

  5. YourChannelName: Run Backstroke Requests Backstroke is a Github bot to keep repository forks up to date with their upstream. Therefore, if you setup your own list of Backstroke URLs, you can run this command to ping all your URLs, so their upstreams are checked whether there are some missing updates.

  6. YourChannelName: Push Local Git Tags Walk through all git repositories and perform the git push --tags command, i.e., perform a git push for all submodules tags to their respective remote repository.

  7. YourChannelName: Fetch All Submodules remote origin Walk through all git repositories and perform the git fetch origin command, i.e., fetch the updates from the origin, using python script which walk recursively into submodules of submodules. This command also which display the remaining time.

  8. YourChannelName: Pull & Rebase all Submodules (git) Walk through all git repositories and perform the git pull --rebase command, i.e., fetch the updates from the origin and merge the changes by rebase, using git submodules which walk recursively into submodules of submodules and performing checkout on their master branch.

  9. YourChannelName: Pull & Rebase all Submodules (python) Walk through all git repositories and perform the git pull --rebase command, i.e., fetch the updates from the origin and merge the changes by rebase, using python script which walk recursively into submodules of submodules but does not checkout on their master branch.

    Notice it is required to they to be checkout on some branch before doing git pull. Then it is useful to run first the command Pull & Rebase all Packages (git) when you first install the git submodules and on the remaining times, call this command which display the remaining time.

  10. YourChannelName: Pull & Rebase all Upstreams (Not Yet Implemented) Walk through all git repositories and perform git remote add upstream_url, checkout on the specified remote branch, and do a git merge with the upstream contents.

  11. YourChannelName: Add All Upstreams Remotes Walk through all git repositories and add as remote their upstream set on the file .gitmodules, if it exists. The upstream will have the username of the upstream user.

  12. YourChannelName: Delete All remote Except origin Walk through all git repositories and delete all remotes which are not origin and the upstream username. This is useful to clean all the remotes repositories after running the find_forks command.

  13. YourChannelName: Extract Default Package Run the script copy_default_package.py which unpack_settings the Default.sublime-package at the on the Packages/../ folder, i.e., on the folder which the Sublime Text loose packages are, not inside it. This command automatically runs when you install a new version of Sublime Text, therefore the command is only here when you want to force it to override the current files.

  14. YourChannelName: Run Stable Installation Run the script channel_installer.py which install all the channel Stable Version packages which are configured to be installed accordingly to the file settings.py at YourChannelName channel repository.

    The installer can only be run once. If the installation was interrupted by closing Sublime Text, you first need to call the command Run Uninstallation to uninstall all the installed packages and only then to call this installer the Run Stable Installation command again.

  15. YourChannelName: Run Development Installation Run the script channel_installer.py which install all the channel Development Version packages which are configured to be installed accordingly to the file settings.py at YourChannelName channel repository.

    The installer can only be run once. If the installation was interrupted by closing Sublime Text, you first need to call the command Run Uninstallation to uninstall all the installed packages and only then to call this installer the Run Stable Installation command again.

  16. YourChannelName: Run Uninstallation Run the script channel_uninstaller.py which uninstall all the channel Stable or Development Version packages which were installed accordingly to the file settings.py at YourChannelName channel repository.

    The uninstaller run multiple, if the uninstallation was interrupted by closing Sublime Text, you can call the command Run Uninstallation continue to uninstall all the installed packages once you start Sublime Text again.

Installation Notes Go to Top

  1. This may show up close to the installation end:

    error: PackagesManager

    error: PackagesManager

The package specified, Package Control, is not installed

                If there will be new messages on the next seconds,
                they will be show on the Sublime Text console

    You can just ignore this. It happens because both PackagesManager and the installer try to uninstall Package Control. Someday this should be fixed, then only one of them attempt to do it. It is not always required to replace the Package Control by the PackagesManager, it depends on the channel configuration. However most of the commands will not work with Package Control. This is because was added some functionality to PackagesManager, which is not present on Package Control.

  2. Currently it has the problem of showing up this error box randomly. This may or may not happen when you run the installer:

    Error Box

    This happens at this moments:

    ignored packages updated to: ["Vintage", "Uncrustify", ..., AdvancedNewFile", "AlignTab"]
reloading settings Packages/User/Preferences.sublime-settings
ignored packages updated to: ["Vintage"]
ignored packages updated to: ["Vintage", "Uncrustify", ..., AdvancedNewFile", "AlignTab"]
reloading settings Packages/User/Preferences.sublime-settings
ignored packages updated to: ["Vintage"]
ignored packages updated to: ["Vintage", "Uncrustify", ..., AdvancedNewFile", "AlignTab"]
reloading settings Packages/User/Preferences.sublime-settings
ignored packages updated to: ["Vintage"]
ignored packages updated to: ["Vintage", "Uncrustify", ..., AdvancedNewFile", "AlignTab"]
reloading settings Packages/User/Preferences.sublime-settings
ignored packages updated to: ["Vintage"]
ignored packages updated to: ["Vintage", "Uncrustify", ..., AdvancedNewFile", "AlignTab"]
reloading settings Packages/User/Preferences.sublime-settings
ignored packages updated to: ["Vintage"]
ignored packages updated to: ["Vintage", "Uncrustify", ..., AdvancedNewFile", "AlignTab"]
reloading settings Packages/User/Preferences.sublime-settings
reloading settings Packages/User/Preferences.sublime-settings

    It appears a package is trying to ignore itself, causing a loop.
    Please resolve by removing the offending ignored_packages setting.

    It is unknown yet what is setting the ignored_packages setting to ["Vintage"]. That is why was wrote this function:

    def add_packages_to_ignored_list(packages_list):
    """
        Something, somewhere is setting the ignored_packages list to `["Vintage"]`. Then ensure we
        override this.
    """
    ignored_packages = g_user_settings.get( "ignored_packages", [] )
    unique_list_append( ignored_packages, packages_list )

    for interval in range( 0, 27 ):
        g_user_settings.set( "ignored_packages", ignored_packages )
        sublime.save_settings( USER_SETTINGS_FILE )

        time.sleep(0.1)

    Perhaps Package Control is doing it, as this error showed up in a vanilla install only with Package Control installed. The problem seems random and does not to happens every time you run the channel installer.

  3. This error also may or may not show up when you run the installer:

    Error while loading PyV8 binary

    emmet.pyv8loader: Unable to download packages list. HTTP error 403 downloading
https://api.github.com/repos/emmetio/pyv8-binaries/contents.
error: Error while loading PyV8 binary: exit code 1
Try to manually install PyV8 from
https://github.com/emmetio/pyv8-binaries

    It seems it cannot always download the pyv8-binaries as the GitHub may be throttling your connection as you just downloaded a lot of contents. So, you can try to manually download the contents at pyv8-binaries or just wait another hour and restart Sublime Text, so the package can download the contents by itself.

  4. Sublime Text may enter on deadlock, while Package Control is installing the missing dependencies. This has a similar issue registered at CoreIssues$1966(Deadlock/hang when batch deleting/creating settings files). The solution to this is to notice when Sublime Text is hanged with no CPU usage, i.e., for some time it is unresponsive, then you need to kill Sublime Text itself or just kill the program called plugin_host or plugin_host.exe. After killing plugin_host, Sublime Text will became responsive again, then you can save your work and restart Sublime Text to restore the Sublime Text packages functionality.

Development Problems

  1. The Development Version currently cannot install the dependencies debugtools and channelmanager as Package Control always unpack package dependencies. Because to install the development packages, it required to they do not exists on the user loose Packages folder. But as Package Control unpacks them when installing the required dependencies, the installer cannot clone and install the files.

    The solution to this problem is to Package Control accept some dependencies to be installed inside a sublime-package. There is a open pull request for Package Control allowing this feature: Pull$1291 Allowed debugtools to be import from a .sublime-package file.

    The work around to fix this, is after the Development Version installation process to be finished, delete the created folders by Package Control and clone these two repositories manually.

  2. If the latest existent tag is on the form 3144, the command which automatically update the tag will fail to increment/create new tags after it, as they fetch the latest tags available from the repository. Currently it is not implemented the code to automatically figure out such tags and then try the get some older tag on the correct format.

  3. Use the form below to test your repository JSON to ensure Package Control will be able to index your package. https://packagecontrol.io/test_repo

License Go to Top

All files in this repository, i.e., excluding its git submodules and the files which include its own license header, are released under GNU General Public License v3.0 or the latest version available on http://www.gnu.org/licenses/gpl.html

For more information see:

  1. The LICENSE file for the GPL v3.0 license
  2. The website https://www.gnu.org/licenses/gpl-3.0.en.html

About

Manages packages installed as git submodules

Resources

Readme

License

GPL-3.0 license
Activity

Stars

3 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases

116 tags

Sponsor this project

Packages

No packages published

Languages