push method

@override Future<void> push(GitFileRepository repository, { String? remote, List<String>? refspecs, bool force = false, bool tags = false, bool setUpstream = false, })

Updates remote with refs of repository (git push), running inside that repository's context.

remote is a configured remote name or a remote location in one of the accepted forms documented on this class. Without remote, git pushes the checked out branch to its default remote. refspecs give the refs to push and the remote names they take (e.g. main:refs/heads/topic); they require remote. A push that would discard the remote's history — it is not a fast-forward — is refused with GitPushRejectedException.

With force, the exchange is not refused for discarding the remote's history: the remote branch moves onto the pushed commit even when the pushed history does not descend from the remote tip (git push --force), so the remote keeps the pushed history instead of refusing the exchange. The commits the remote branch leaves behind stay in the remote repository as objects until git collects them. Every other failure stays typed.

With tags, every local tag is pushed alongside the other refs; a tag the remote already holds with another value is refused with GitPushRejectedException.

With setUpstream, the pushed local branch follows its remote branch once the push succeeded, so a later pull without arguments follows it. It requires the refspecs to designate exactly one local branch — refs/heads/<name>, <name>, with an optional destination — or no refspecs at all while HEAD is attached to a branch; anything else, a detached HEAD included, is refused with ArgumentError before git runs. Without refspecs, that branch is pushed by name to remote; without remote too, what is pushed stays the choice of the repository's own configuration.

Throws GitUnsupportedUrlException without running git when remote is not in an accepted form, GitAuthenticationException when the remote refused or demanded credentials, GitRemoteUnreachableException when the remote host could not be reached, and GitRemoteRepositoryNotFoundException when no repository exists at the remote location.

Implementation

@override
Future<void> push(
  GitFileRepository repository, {
  String? remote,
  List<String>? refspecs,
  bool force = false,
  bool tags = false,
  bool setUpstream = false,
}) async {
  final List<String> refspecList = refspecs ?? const <String>[];
  if (refspecList.isNotEmpty && remote == null) {
    throw ArgumentError.value(
      refspecList,
      'refspecs',
      'require a remote, otherwise nothing would be pushed',
    );
  }
  final List<String> effectiveRefspecs = setUpstream
      ? await _setUpstreamRefspecs(repository, remote, refspecList)
      : refspecList;
  if (remote != null) {
    classifyRemoteLocation(remote);
  }
  await _exchange(repository, <String>[
    'push',
    if (force) '--force',
    if (tags) '--tags',
    if (setUpstream) '--set-upstream',
    if (remote != null) ...<String>['--', remote],
    ...effectiveRefspecs,
  ]);
}