GitPush does not work

[GertJanBoender]

I downloaded the great GIT package.
The GitCommit works fine.
The GitPush did not work as expected.
I could not solve this, because the documentation is not available for GitPush.
Is there documentation for GitPush?

I added a text copy of my Mathematica code:

(* GitLink of GitLink-2018.07.20.01.paclet *)

Needs["GitLink`"]

(* repo on computer *)

workingRepo=GitOpen[NotebookDirectory[]]

GitProperties[workingRepo]

(* git properties of of working repo:

 \[LeftAssociation]"HEAD"\[Rule]"refs/heads/master",

"HeadBranch"[Rule]"master",
"ShallowQ"[Rule]False,
"EmptyQ"[Rule]False,
"UnbornHeadQ"[Rule]False,
"BareQ"[Rule]False,
"GitDirectory"[Rule]"\\WURNET.NL\Homes\boend001\My Documents\2020\1600002031 EU H2020 VACDIVA\.git\",
"WorkingDirectory"[Rule]"\\WURNET.NL\Homes\boend001\My Documents\2020\1600002031 EU H2020 VACDIVA\",
"DetachedHeadQ"[Rule]False,
"Namespace"[Rule]$Failed,
"State"[Rule]"None",
"Conflicts"[Rule]{},
"Remotes"[Rule][LeftAssociation]"origin"[Rule][LeftAssociation]"FetchURL"[Rule]"git@git.wur.nl:wbvr_epi/vacdiva2020.git","PushURL"[Rule]"git@git.wur.nl:wbvr_epi/vacdiva2020.git","FetchRefSpecs"[Rule]{"+refs/heads/:refs/remotes/origin/"},"PushRefSpecs"[Rule]{}[RightAssociation][RightAssociation],
"LocalBranches"[Rule]{"master"},
"RemoteBranches"[Rule]{"origin/master"},
"Tags"[Rule]{}[RightAssociation] *)

!(*
StyleBox[
RowBox[{
RowBox[{
StyleBox[
RowBox[{"(",
StyleBox[
StyleBox["", "InformationUsageText",
StripOnInput->False,
LineSpacing->{1.5, 1.5, 3.}], "InformationUsageText",
StripOnInput->False,
LineSpacing->{1.5, 1.5, 3.}]}]],
StyleBox[
StyleBox["\n", "InformationUsageText",
StripOnInput->False,
LineSpacing->{1.5, 1.5, 3.}], "InformationUsageText",
StripOnInput->False,
LineSpacing->{1.5, 1.5, 3.}],
RowBox[{
RowBox[{
RowBox[{"GitLink`GitPush",
StyleBox[" ", "InformationUsageText",
StripOnInput->False,
LineSpacing->{1.5, 1.5, 3.}], "does", " ", "not", " ", "provide", " ", "a"}], " ", "<", "local", ">", " ",
RowBox[{"documentation", " ", "page"}]}], ",", " ",
RowBox[{"while", " ", "other", " ", "function", " ", "do"}]}],
StyleBox["\n", "InformationUsageText",
StripOnInput->False,
LineSpacing->{1.5, 1.5, 3.}], " ", ")"}], " "}], "InformationUsageText",
StripOnInput->False,
LineSpacing->{1.5, 1.5, 3.}])

?"GitLink`*"

(* remote repo *)

remoteRepo="origin";

(* test of proper remote repo : result is TRUE *)

GitRemoteQ[workingRepo,remoteRepo]

GitPush[workingRepo,remoteRepo,"origin/master"]

(* Output Error:
StringForm::sfr: "Item !(*RowBox[{"1"}]) requested in "!(*RowBox[{"\"The git remote failed to connect with the error \\\"1\\\".\""}])" out of range; !(*RowBox[{"0"}]) items available."
""GitPush::noconnect: "The git remote failed to connect with the error "1"."
False
*)

(*
The documentation is not available
What should I change to get the GitPush working?
*)
GitTest.pdf

[jfultz]

First, nothing will work if GitFetch doesn't work. I.e., the transport protocol needs to be functioning. So, before you read anything else, ensure that the fully documented and supported GitFetch works. Unfortunately, GitLink doesn't support the full range of transport protocols, and doing so is a lot of detailed fiddly work that's not likely to be done by me anytime soon. I've implemented the protocols I need (in true, open source fashion 😄 ).

The reason GitPush isn't documented is because right now the only acceptable form is a modestly user-hostile form used internally by git, and I wasn't eager to document that. But it works, and we've used it plenty internally at Wolfram. The syntax is GitPush[repo_GitRepo, remote_String, refspec_String]. Which seems simple enough. Except that most of the things you think might work for refspec don't.

See the documentation for refspec here (second item under the Options heading). There are limitations on what can be used...some I remember for sure and some may or may not be limitations...I can't recall for certain what's supported by the current libgit2 git_remote_upload function:

• Inferencing of the refs/heads/ namespace is not supported; you absolutely must include that explicitly for source and destination
• I don't recall, but I think that it doesn't auto-detect the upstream branch, and so you must use the source:dest form of the refspec to explicitly specify source branch (in your local repo) and the destination branch (in the remote repo)
• There's no force option, so you must use + if you want to force push
• I honestly don't think I've ever tried pushing tags; it's unclear to me whether just using a refspec in the refs/tags/ namespace would work or not.

Since I originally wrote this, libgit2 added a git_remote_push() function (yes, this was originally written so long ago that libgit2 didn't even have a properly codified push). It's unclear to me whether reimplementing this with git_remote_push() would do all of the expected refspec inferencing/upstream detection/etc., or whether I'll have to replicate that logic in GitLink.

If you want to see examples that work, check out the GitPush tests in Push.wl. These tests do work, except that they refer to a remote that you won't have access to.

In summary, it does work...with limitations and user hostility that I'll acknowledge. None of these is a bug. But there are certainly features that could be improved here.