34
$\begingroup$

In the current phase of the project I am working on I am developing a utility package which could easily be open-sourced and shared with the community IF there was an =easy= way to share a notebook / package to GitHub.

I looked at this question which seems to involve too much work to setup, also it doesn't look 'current' at all.

I also found the GitLink project which looks easier to handle.

Before I'll download and install GitLink and perhaps might lose to much valuable time experimenting with it, I would like to know if it is possible to store notebooks to GitHub with GitLink?

What do you suggest, advise on how to store Notebooks and packages to Github?

=== UPDATE 1-feb-17 ===

I installed the GitLink paclet from: this location. It will take time to experiment with this new ( experimental? ) functionality.

Improve this question
$\endgroup$
15
  • 3
    $\begingroup$ I've just updated my Phylogenetics package on GitHub, you might find their architecture to your taste. The process is easy: register to GitHub, create a repository, upload your files to it, create a release and share the permanent link pointing to the latest release. You don't have to install anything. $\endgroup$
    – István Zachar
    Jan 31, 2017 at 12:58
  • 10
    $\begingroup$ I see why this might be considered off topic (there is one close vote), but I think it should be left open. It will be a great benefit to the community to clear this up to those who are new to GitHub and version control. $\endgroup$
    – Szabolcs
    Jan 31, 2017 at 13:09
  • 1
    $\begingroup$ Why do you want to put your package on GitHub? Is it just to publish it, or is to to use version control and develop the package in the open? GitHub is became the de facto home for open source projects so many people look at it as a package publishing platform. I have seen people upload a zip file of an M package just to publish it. But it's purpose isn't really publishing. It is version control and open collaborative development. This latter use requires more effort to get familiar with. $\endgroup$
    – Szabolcs
    Jan 31, 2017 at 13:20
  • 2
    $\begingroup$ Yes, but that is just a way to use git through the Wolfram Language (as opposed to using it through the command line or through a GUI). It does not make things easier unless your goal is automation from within Mathematica. $\endgroup$
    – Szabolcs
    Jan 31, 2017 at 13:33
  • 3
    $\begingroup$ You might also be interested in the discussion and links here: How to share a notebook? $\endgroup$
    – MarcoB
    Jan 31, 2017 at 15:17

2 Answers 2

Reset to default
24
$\begingroup$

General comment

Your question suggests that you might be on the wrong or at least on a stony path. Let me try to clear some things up even if it is not strictly Mathematica correlated.

Yes, you can share your package via GitHub, but you might confuse things here. The primary purpose of GitHub is to provide an online platform for the version control system git. When you publish a complete Mathematica package, it is more like publishing a release of software. GitHub has this feature and lets you publish releases, but it is not its primary purpose.

You should use git when you want to track the progress during the coding of the package. If you want to make your code public or you are working with several other people on the same code (the other main purpose of git), then GitHub is the place to go. With git you can track changes, you can work on several features simultaneously, you can track bugs by comparing different versions of files, and much much more. RM wrote an excellent answer once that explained package development in more detail:

Additional helpful features of GitHub are that

  • you have an issue tracker where people can tell you about things that don't work
  • you can create documentation pages quickly because it provides a markdown wiki for each repository
  • you can upload several releases of your software that users can download

When you don't know git, don't start with GitLink

GitLink is an API that makes it possible to use git from within Mathematica. If you don't know git, then this might not be the way you want to go. It is like using MathLink without knowing C.

If you indeed want to learn how to use version control, then start with a simple tutorial to understand the basics. I don't expect you to work on commandline but there are very nice GUIs for git. On OSX or Windows I highly recommend SourceTree, and on Linux, you could use for instance gitk.

I want to note that IntelliJ Idea as other good IDEs as well has extremely nice git support right out of the box. If you use it with the Mathematica Plugin you can develop packages and have all those features in one tool.

If you only want to share the final package

Well, you can go to GitHub as well. Just create an account and a new repository. Put in a decent README.md and upload your package.zip in the release section. You don't have to know any git command for this. It can all be done with some mouse clicks.

How should I see "paclets" in this context?

Paclets are the future way how you should distribute your packages. The problem is that the documentation is currently non-existent. My background info on paclets is very vague, but I believe paclets started as containers for additional data like CUDA drivers or for all the XXXData functions like ChemicalData. I'm not sure if it was planned from the beginning, but paclets seem to be the future of package-distribution.

For a good resource on how to use them with your own packages, you should read Szabolcs post:

Improve this answer
$\endgroup$
4
  • $\begingroup$ This is merely the outline of an answer. If there are things I should explain in greater depth, you are welcome to leave a comment. $\endgroup$
    – halirutan ♦
    Feb 1, 2017 at 16:02
  • $\begingroup$ Thanks. This cleared up a lot of points. - How should I see "paclets" in this context? When should you use paclets? $\endgroup$
    – nilo de roock
    Feb 1, 2017 at 18:19
  • 1
    $\begingroup$ @niloderoock See my update at the end of my post. $\endgroup$
    – halirutan ♦
    Feb 1, 2017 at 18:56
  • $\begingroup$ Interesting. This is clearly a volatile area. $\endgroup$
    – nilo de roock
    Feb 1, 2017 at 20:38
11
$\begingroup$

There is ResourceFunction["SaveReadableNotebook"]:

SaveReadableNotebook can be used to create notebook files that are well suited for version control systems that look at changes to files on a line-by-line basis.

It is better to use it with the option "ExcludedCellOptions":

ResourceFunction["SaveReadableNotebook"]["original.nb", "original_readable.nb", 
  "ExcludedCellOptions" -> {CellChangeTimes, ExpressionUUID, CellLabel}];

The formatted notebook file still opens normally:

NotebookOpen["original_readable.nb"]
Improve this answer
$\endgroup$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.