1 /*
2 * Copyright (C) 2008, 2009 Google Inc.
3 * Copyright (C) 2008, Marek Zawirski <marek.zawirski@gmail.com>
4 * Copyright (C) 2008, Robin Rosenberg <robin.rosenberg@dewire.com>
5 * Copyright (C) 2008, 2022 Shawn O. Pearce <spearce@spearce.org> and others
6 *
7 * This program and the accompanying materials are made available under the
8 * terms of the Eclipse Distribution License v. 1.0 which is available at
9 * https://www.eclipse.org/org/documents/edl-v10.php.
10 *
11 * SPDX-License-Identifier: BSD-3-Clause
12 */
13
14 package org.eclipse.jgit.transport;
15
16 import static java.nio.charset.StandardCharsets.UTF_8;
17 import static java.util.Objects.requireNonNull;
18
19 import java.io.BufferedReader;
20 import java.io.IOException;
21 import java.io.InputStreamReader;
22 import java.io.OutputStream;
23 import java.io.PrintStream;
24 import java.lang.ref.WeakReference;
25 import java.lang.reflect.Field;
26 import java.lang.reflect.Modifier;
27 import java.net.URISyntaxException;
28 import java.net.URL;
29 import java.text.MessageFormat;
30 import java.time.Instant;
31 import java.util.ArrayList;
32 import java.util.Collection;
33 import java.util.Collections;
34 import java.util.Enumeration;
35 import java.util.LinkedHashSet;
36 import java.util.LinkedList;
37 import java.util.List;
38 import java.util.Map;
39 import java.util.Vector;
40 import java.util.concurrent.CopyOnWriteArrayList;
41
42 import org.eclipse.jgit.annotations.NonNull;
43 import org.eclipse.jgit.annotations.Nullable;
44 import org.eclipse.jgit.errors.NotSupportedException;
45 import org.eclipse.jgit.errors.TransportException;
46 import org.eclipse.jgit.hooks.Hooks;
47 import org.eclipse.jgit.hooks.PrePushHook;
48 import org.eclipse.jgit.internal.JGitText;
49 import org.eclipse.jgit.lib.Constants;
50 import org.eclipse.jgit.lib.ObjectChecker;
51 import org.eclipse.jgit.lib.ObjectId;
52 import org.eclipse.jgit.lib.ProgressMonitor;
53 import org.eclipse.jgit.lib.Ref;
54 import org.eclipse.jgit.lib.Repository;
55 import org.eclipse.jgit.storage.pack.PackConfig;
56
57 /**
58 * Connects two Git repositories together and copies objects between them.
59 * <p>
60 * A transport can be used for either fetching (copying objects into the
61 * caller's repository from the remote repository) or pushing (copying objects
62 * into the remote repository from the caller's repository). Each transport
63 * implementation is responsible for the details associated with establishing
64 * the network connection(s) necessary for the copy, as well as actually
65 * shuffling data back and forth.
66 * <p>
67 * Transport instances and the connections they create are not thread-safe.
68 * Callers must ensure a transport is accessed by only one thread at a time.
69 */
70 public abstract class Transport implements AutoCloseable {
71 /** Type of operation a Transport is being opened for. */
72 public enum Operation {
73 /** Transport is to fetch objects locally. */
74 FETCH,
75 /** Transport is to push objects remotely. */
76 PUSH;
77 }
78
79 private static final List<WeakReference<TransportProtocol>> protocols =
80 new CopyOnWriteArrayList<>();
81
82 static {
83 // Registration goes backwards in order of priority.
84 register(TransportLocal.PROTO_LOCAL);
85 register(TransportBundleFile.PROTO_BUNDLE);
86 register(TransportAmazonS3.PROTO_S3);
87 register(TransportGitAnon.PROTO_GIT);
88 register(TransportSftp.PROTO_SFTP);
89 register(TransportHttp.PROTO_FTP);
90 register(TransportHttp.PROTO_HTTP);
91 register(TransportGitSsh.PROTO_SSH);
92
93 registerByService();
94 }
95
96 private static void registerByService() {
97 ClassLoader ldr = Thread.currentThread().getContextClassLoader();
98 if (ldr == null)
99 ldr = Transport.class.getClassLoader();
100 Enumeration<URL> catalogs = catalogs(ldr);
101 while (catalogs.hasMoreElements())
102 scan(ldr, catalogs.nextElement());
103 }
104
105 private static Enumeration<URL> catalogs(ClassLoader ldr) {
106 try {
107 String prefix = "META-INF/services/"; //$NON-NLS-1$
108 String name = prefix + Transport.class.getName();
109 return ldr.getResources(name);
110 } catch (IOException err) {
111 return new Vector<URL>().elements();
112 }
113 }
114
115 private static void scan(ClassLoader ldr, URL url) {
116 try (BufferedReader br = new BufferedReader(
117 new InputStreamReader(url.openStream(), UTF_8))) {
118 String line;
119 while ((line = br.readLine()) != null) {
120 line = line.trim();
121 if (line.length() == 0)
122 continue;
123 int comment = line.indexOf('#');
124 if (comment == 0)
125 continue;
126 if (comment != -1)
127 line = line.substring(0, comment).trim();
128 load(ldr, line);
129 }
130 } catch (IOException e) {
131 // Ignore errors
132 }
133 }
134
135 private static void load(ClassLoader ldr, String cn) {
136 Class<?> clazz;
137 try {
138 clazz = Class.forName(cn, false, ldr);
139 } catch (ClassNotFoundException notBuiltin) {
140 // Doesn't exist, even though the service entry is present.
141 //
142 return;
143 }
144
145 for (Field f : clazz.getDeclaredFields()) {
146 if ((f.getModifiers() & Modifier.STATIC) == Modifier.STATIC
147 && TransportProtocol.class.isAssignableFrom(f.getType())) {
148 TransportProtocol proto;
149 try {
150 proto = (TransportProtocol) f.get(null);
151 } catch (IllegalArgumentException | IllegalAccessException e) {
152 // If we cannot access the field, don't.
153 continue;
154 }
155 if (proto != null)
156 register(proto);
157 }
158 }
159 }
160
161 /**
162 * Register a TransportProtocol instance for use during open.
163 * <p>
164 * Protocol definitions are held by WeakReference, allowing them to be
165 * garbage collected when the calling application drops all strongly held
166 * references to the TransportProtocol. Therefore applications should use a
167 * singleton pattern as described in
168 * {@link org.eclipse.jgit.transport.TransportProtocol}'s class
169 * documentation to ensure their protocol does not get disabled by garbage
170 * collection earlier than expected.
171 * <p>
172 * The new protocol is registered in front of all earlier protocols, giving
173 * it higher priority than the built-in protocol definitions.
174 *
175 * @param proto
176 * the protocol definition. Must not be null.
177 */
178 public static void register(TransportProtocol proto) {
179 protocols.add(0, new WeakReference<>(proto));
180 }
181
182 /**
183 * Unregister a TransportProtocol instance.
184 * <p>
185 * Unregistering a protocol usually isn't necessary, as protocols are held
186 * by weak references and will automatically clear when they are garbage
187 * collected by the JVM. Matching is handled by reference equality, so the
188 * exact reference given to {@link #register(TransportProtocol)} must be
189 * used.
190 *
191 * @param proto
192 * the exact object previously given to register.
193 */
194 public static void unregister(TransportProtocol proto) {
195 for (WeakReference<TransportProtocol> ref : protocols) {
196 TransportProtocol refProto = ref.get();
197 if (refProto == null || refProto == proto)
198 protocols.remove(ref);
199 }
200 }
201
202 /**
203 * Obtain a copy of the registered protocols.
204 *
205 * @return an immutable copy of the currently registered protocols.
206 */
207 public static List<TransportProtocol> getTransportProtocols() {
208 int cnt = protocols.size();
209 List<TransportProtocol> res = new ArrayList<>(cnt);
210 for (WeakReference<TransportProtocol> ref : protocols) {
211 TransportProtocol proto = ref.get();
212 if (proto != null)
213 res.add(proto);
214 else
215 protocols.remove(ref);
216 }
217 return Collections.unmodifiableList(res);
218 }
219
220 /**
221 * Open a new transport instance to connect two repositories.
222 * <p>
223 * This method assumes
224 * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}.
225 *
226 * @param local
227 * existing local repository.
228 * @param remote
229 * location of the remote repository - may be URI or remote
230 * configuration name.
231 * @return the new transport instance. Never null. In case of multiple URIs
232 * in remote configuration, only the first is chosen.
233 * @throws java.net.URISyntaxException
234 * the location is not a remote defined in the configuration
235 * file and is not a well-formed URL.
236 * @throws org.eclipse.jgit.errors.NotSupportedException
237 * the protocol specified is not supported.
238 * @throws org.eclipse.jgit.errors.TransportException
239 * the transport cannot open this URI.
240 */
241 public static Transport open(Repository local, String remote)
242 throws NotSupportedException, URISyntaxException,
243 TransportException {
244 return open(local, remote, Operation.FETCH);
245 }
246
247 /**
248 * Open a new transport instance to connect two repositories.
249 *
250 * @param local
251 * existing local repository.
252 * @param remote
253 * location of the remote repository - may be URI or remote
254 * configuration name.
255 * @param op
256 * planned use of the returned Transport; the URI may differ
257 * based on the type of connection desired.
258 * @return the new transport instance. Never null. In case of multiple URIs
259 * in remote configuration, only the first is chosen.
260 * @throws java.net.URISyntaxException
261 * the location is not a remote defined in the configuration
262 * file and is not a well-formed URL.
263 * @throws org.eclipse.jgit.errors.NotSupportedException
264 * the protocol specified is not supported.
265 * @throws org.eclipse.jgit.errors.TransportException
266 * the transport cannot open this URI.
267 */
268 public static Transport open(final Repository local, final String remote,
269 final Operation op) throws NotSupportedException,
270 URISyntaxException, TransportException {
271 if (local != null) {
272 final RemoteConfig cfg = new RemoteConfig(local.getConfig(), remote);
273 if (doesNotExist(cfg)) {
274 return open(local, new URIish(remote), null);
275 }
276 return open(local, cfg, op);
277 }
278 return open(new URIish(remote));
279
280 }
281
282 /**
283 * Open new transport instances to connect two repositories.
284 * <p>
285 * This method assumes
286 * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}.
287 *
288 * @param local
289 * existing local repository.
290 * @param remote
291 * location of the remote repository - may be URI or remote
292 * configuration name.
293 * @return the list of new transport instances for every URI in remote
294 * configuration.
295 * @throws java.net.URISyntaxException
296 * the location is not a remote defined in the configuration
297 * file and is not a well-formed URL.
298 * @throws org.eclipse.jgit.errors.NotSupportedException
299 * the protocol specified is not supported.
300 * @throws org.eclipse.jgit.errors.TransportException
301 * the transport cannot open this URI.
302 */
303 public static List<Transport> openAll(final Repository local,
304 final String remote) throws NotSupportedException,
305 URISyntaxException, TransportException {
306 return openAll(local, remote, Operation.FETCH);
307 }
308
309 /**
310 * Open new transport instances to connect two repositories.
311 *
312 * @param local
313 * existing local repository.
314 * @param remote
315 * location of the remote repository - may be URI or remote
316 * configuration name.
317 * @param op
318 * planned use of the returned Transport; the URI may differ
319 * based on the type of connection desired.
320 * @return the list of new transport instances for every URI in remote
321 * configuration.
322 * @throws java.net.URISyntaxException
323 * the location is not a remote defined in the configuration
324 * file and is not a well-formed URL.
325 * @throws org.eclipse.jgit.errors.NotSupportedException
326 * the protocol specified is not supported.
327 * @throws org.eclipse.jgit.errors.TransportException
328 * the transport cannot open this URI.
329 */
330 public static List<Transport> openAll(final Repository local,
331 final String remote, final Operation op)
332 throws NotSupportedException, URISyntaxException,
333 TransportException {
334 final RemoteConfig cfg = new RemoteConfig(local.getConfig(), remote);
335 if (doesNotExist(cfg)) {
336 final ArrayList<Transport> transports = new ArrayList<>(1);
337 transports.add(open(local, new URIish(remote), null));
338 return transports;
339 }
340 return openAll(local, cfg, op);
341 }
342
343 /**
344 * Open a new transport instance to connect two repositories.
345 * <p>
346 * This method assumes
347 * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}.
348 *
349 * @param local
350 * existing local repository.
351 * @param cfg
352 * configuration describing how to connect to the remote
353 * repository.
354 * @return the new transport instance. Never null. In case of multiple URIs
355 * in remote configuration, only the first is chosen.
356 * @throws org.eclipse.jgit.errors.NotSupportedException
357 * the protocol specified is not supported.
358 * @throws org.eclipse.jgit.errors.TransportException
359 * the transport cannot open this URI.
360 * @throws java.lang.IllegalArgumentException
361 * if provided remote configuration doesn't have any URI
362 * associated.
363 */
364 public static Transport open(Repository local, RemoteConfig cfg)
365 throws NotSupportedException, TransportException {
366 return open(local, cfg, Operation.FETCH);
367 }
368
369 /**
370 * Open a new transport instance to connect two repositories.
371 *
372 * @param local
373 * existing local repository.
374 * @param cfg
375 * configuration describing how to connect to the remote
376 * repository.
377 * @param op
378 * planned use of the returned Transport; the URI may differ
379 * based on the type of connection desired.
380 * @return the new transport instance. Never null. In case of multiple URIs
381 * in remote configuration, only the first is chosen.
382 * @throws org.eclipse.jgit.errors.NotSupportedException
383 * the protocol specified is not supported.
384 * @throws org.eclipse.jgit.errors.TransportException
385 * the transport cannot open this URI.
386 * @throws java.lang.IllegalArgumentException
387 * if provided remote configuration doesn't have any URI
388 * associated.
389 */
390 public static Transport open(final Repository local,
391 final RemoteConfig cfg, final Operation op)
392 throws NotSupportedException, TransportException {
393 final List<URIish> uris = getURIs(cfg, op);
394 if (uris.isEmpty())
395 throw new IllegalArgumentException(MessageFormat.format(
396 JGitText.get().remoteConfigHasNoURIAssociated, cfg.getName()));
397 final Transport tn = open(local, uris.get(0), cfg.getName());
398 tn.applyConfig(cfg);
399 return tn;
400 }
401
402 /**
403 * Open new transport instances to connect two repositories.
404 * <p>
405 * This method assumes
406 * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}.
407 *
408 * @param local
409 * existing local repository.
410 * @param cfg
411 * configuration describing how to connect to the remote
412 * repository.
413 * @return the list of new transport instances for every URI in remote
414 * configuration.
415 * @throws org.eclipse.jgit.errors.NotSupportedException
416 * the protocol specified is not supported.
417 * @throws org.eclipse.jgit.errors.TransportException
418 * the transport cannot open this URI.
419 */
420 public static List<Transport> openAll(final Repository local,
421 final RemoteConfig cfg) throws NotSupportedException,
422 TransportException {
423 return openAll(local, cfg, Operation.FETCH);
424 }
425
426 /**
427 * Open new transport instances to connect two repositories.
428 *
429 * @param local
430 * existing local repository.
431 * @param cfg
432 * configuration describing how to connect to the remote
433 * repository.
434 * @param op
435 * planned use of the returned Transport; the URI may differ
436 * based on the type of connection desired.
437 * @return the list of new transport instances for every URI in remote
438 * configuration.
439 * @throws org.eclipse.jgit.errors.NotSupportedException
440 * the protocol specified is not supported.
441 * @throws org.eclipse.jgit.errors.TransportException
442 * the transport cannot open this URI.
443 */
444 public static List<Transport> openAll(final Repository local,
445 final RemoteConfig cfg, final Operation op)
446 throws NotSupportedException, TransportException {
447 final List<URIish> uris = getURIs(cfg, op);
448 final List<Transport> transports = new ArrayList<>(uris.size());
449 for (URIish uri : uris) {
450 final Transport tn = open(local, uri, cfg.getName());
451 tn.applyConfig(cfg);
452 transports.add(tn);
453 }
454 return transports;
455 }
456
457 private static List<URIish> getURIs(final RemoteConfig cfg,
458 final Operation op) {
459 switch (op) {
460 case FETCH:
461 return cfg.getURIs();
462 case PUSH: {
463 List<URIish> uris = cfg.getPushURIs();
464 if (uris.isEmpty())
465 uris = cfg.getURIs();
466 return uris;
467 }
468 default:
469 throw new IllegalArgumentException(op.toString());
470 }
471 }
472
473 private static boolean doesNotExist(RemoteConfig cfg) {
474 return cfg.getURIs().isEmpty() && cfg.getPushURIs().isEmpty();
475 }
476
477 /**
478 * Open a new transport instance to connect two repositories.
479 *
480 * @param local
481 * existing local repository.
482 * @param uri
483 * location of the remote repository.
484 * @return the new transport instance. Never null.
485 * @throws org.eclipse.jgit.errors.NotSupportedException
486 * the protocol specified is not supported.
487 * @throws org.eclipse.jgit.errors.TransportException
488 * the transport cannot open this URI.
489 */
490 public static Transport open(Repository local, URIish uri)
491 throws NotSupportedException, TransportException {
492 return open(local, uri, null);
493 }
494
495 /**
496 * Open a new transport instance to connect two repositories.
497 *
498 * @param local
499 * existing local repository.
500 * @param uri
501 * location of the remote repository.
502 * @param remoteName
503 * name of the remote, if the remote as configured in
504 * {@code local}; otherwise null.
505 * @return the new transport instance. Never null.
506 * @throws org.eclipse.jgit.errors.NotSupportedException
507 * the protocol specified is not supported.
508 * @throws org.eclipse.jgit.errors.TransportException
509 * the transport cannot open this URI.
510 */
511 public static Transport open(Repository local, URIish uri, String remoteName)
512 throws NotSupportedException, TransportException {
513 for (WeakReference<TransportProtocol> ref : protocols) {
514 TransportProtocol proto = ref.get();
515 if (proto == null) {
516 protocols.remove(ref);
517 continue;
518 }
519
520 if (proto.canHandle(uri, local, remoteName)) {
521 Transport tn = proto.open(uri, local, remoteName);
522 tn.prePush = Hooks.prePush(local, tn.hookOutRedirect);
523 tn.prePush.setRemoteLocation(uri.toString());
524 tn.prePush.setRemoteName(remoteName);
525 return tn;
526 }
527 }
528
529 throw new NotSupportedException(MessageFormat.format(JGitText.get().URINotSupported, uri));
530 }
531
532 /**
533 * Open a new transport with no local repository.
534 * <p>
535 * Note that the resulting transport instance can not be used for fetching
536 * or pushing, but only for reading remote refs.
537 *
538 * @param uri a {@link org.eclipse.jgit.transport.URIish} object.
539 * @return new Transport instance
540 * @throws org.eclipse.jgit.errors.NotSupportedException
541 * @throws org.eclipse.jgit.errors.TransportException
542 */
543 public static Transport open(URIish uri) throws NotSupportedException, TransportException {
544 for (WeakReference<TransportProtocol> ref : protocols) {
545 TransportProtocol proto = ref.get();
546 if (proto == null) {
547 protocols.remove(ref);
548 continue;
549 }
550
551 if (proto.canHandle(uri, null, null))
552 return proto.open(uri);
553 }
554
555 throw new NotSupportedException(MessageFormat.format(JGitText.get().URINotSupported, uri));
556 }
557
558 /**
559 * Convert push remote refs update specification from
560 * {@link org.eclipse.jgit.transport.RefSpec} form to
561 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands
562 * wildcards by matching source part to local refs. expectedOldObjectId in
563 * RemoteRefUpdate is set when specified in leases. Tracking branch is
564 * configured if RefSpec destination matches source of any fetch ref spec
565 * for this transport remote configuration.
566 *
567 * @param db
568 * local database.
569 * @param specs
570 * collection of RefSpec to convert.
571 * @param leases
572 * map from ref to lease (containing expected old object id)
573 * @param fetchSpecs
574 * fetch specifications used for finding localtracking refs. May
575 * be null or empty collection.
576 * @return collection of set up
577 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}.
578 * @throws java.io.IOException
579 * when problem occurred during conversion or specification set
580 * up: most probably, missing objects or refs.
581 * @since 4.7
582 */
583 public static Collection<RemoteRefUpdate> findRemoteRefUpdatesFor(
584 final Repository db, final Collection<RefSpec> specs,
585 final Map<String, RefLeaseSpec> leases,
586 Collection<RefSpec> fetchSpecs) throws IOException {
587 if (fetchSpecs == null)
588 fetchSpecs = Collections.emptyList();
589 final List<RemoteRefUpdate> result = new LinkedList<>();
590 final Collection<RefSpec> procRefs = expandPushWildcardsFor(db, specs);
591
592 for (RefSpec spec : procRefs) {
593 if (spec.isMatching()) {
594 result.add(new RemoteRefUpdate(db, spec.isForceUpdate(),
595 fetchSpecs));
596 continue;
597 }
598 String srcSpec = spec.getSource();
599 final Ref srcRef = db.findRef(srcSpec);
600 if (srcRef != null)
601 srcSpec = srcRef.getName();
602
603 String destSpec = spec.getDestination();
604 if (destSpec == null) {
605 // No destination (no-colon in ref-spec), DWIMery assumes src
606 //
607 destSpec = srcSpec;
608 }
609
610 if (srcRef != null && !destSpec.startsWith(Constants.R_REFS)) {
611 // Assume the same kind of ref at the destination, e.g.
612 // "refs/heads/foo:master", DWIMery assumes master is also
613 // under "refs/heads/".
614 //
615 final String n = srcRef.getName();
616 final int kindEnd = n.indexOf('/', Constants.R_REFS.length());
617 destSpec = n.substring(0, kindEnd + 1) + destSpec;
618 }
619
620 final boolean forceUpdate = spec.isForceUpdate();
621 final String localName = findTrackingRefName(destSpec, fetchSpecs);
622 final RefLeaseSpec leaseSpec = leases.get(destSpec);
623 final ObjectId expected = leaseSpec == null ? null :
624 db.resolve(leaseSpec.getExpected());
625 final RemoteRefUpdate rru = new RemoteRefUpdate(db, srcSpec,
626 destSpec, forceUpdate, localName, expected);
627 result.add(rru);
628 }
629 return result;
630 }
631
632 /**
633 * Convert push remote refs update specification from
634 * {@link org.eclipse.jgit.transport.RefSpec} form to
635 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands
636 * wildcards by matching source part to local refs. expectedOldObjectId in
637 * RemoteRefUpdate is always set as null. Tracking branch is configured if
638 * RefSpec destination matches source of any fetch ref spec for this
639 * transport remote configuration.
640 *
641 * @param db
642 * local database.
643 * @param specs
644 * collection of RefSpec to convert.
645 * @param fetchSpecs
646 * fetch specifications used for finding localtracking refs. May
647 * be null or empty collection.
648 * @return collection of set up
649 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}.
650 * @throws java.io.IOException
651 * when problem occurred during conversion or specification set
652 * up: most probably, missing objects or refs.
653 */
654 public static Collection<RemoteRefUpdate> findRemoteRefUpdatesFor(
655 final Repository db, final Collection<RefSpec> specs,
656 Collection<RefSpec> fetchSpecs) throws IOException {
657 return findRemoteRefUpdatesFor(db, specs, Collections.emptyMap(),
658 fetchSpecs);
659 }
660
661 private static Collection<RefSpec> expandPushWildcardsFor(
662 final Repository db, final Collection<RefSpec> specs)
663 throws IOException {
664 final Collection<RefSpec> procRefs = new LinkedHashSet<>();
665
666 List<Ref> localRefs = null;
667 for (RefSpec spec : specs) {
668 if (!spec.isMatching() && spec.isWildcard()) {
669 if (localRefs == null) {
670 localRefs = db.getRefDatabase().getRefs();
671 }
672 for (Ref localRef : localRefs) {
673 if (spec.matchSource(localRef)) {
674 procRefs.add(spec.expandFromSource(localRef));
675 }
676 }
677 } else {
678 procRefs.add(spec);
679 }
680 }
681 return procRefs;
682 }
683
684 static String findTrackingRefName(final String remoteName,
685 final Collection<RefSpec> fetchSpecs) {
686 // try to find matching tracking refs
687 for (RefSpec fetchSpec : fetchSpecs) {
688 if (fetchSpec.matchSource(remoteName)) {
689 if (fetchSpec.isWildcard()) {
690 return fetchSpec.expandFromSource(remoteName)
691 .getDestination();
692 }
693 return fetchSpec.getDestination();
694 }
695 }
696 return null;
697 }
698
699 /**
700 * Default setting for {@link #fetchThin} option.
701 */
702 public static final boolean DEFAULT_FETCH_THIN = true;
703
704 /**
705 * Default setting for {@link #pushThin} option.
706 */
707 public static final boolean DEFAULT_PUSH_THIN = false;
708
709 /**
710 * Specification for fetch or push operations, to fetch or push all tags.
711 * Acts as --tags.
712 */
713 public static final RefSpec REFSPEC_TAGS = new RefSpec(
714 "refs/tags/*:refs/tags/*"); //$NON-NLS-1$
715
716 /**
717 * Specification for push operation, to push all refs under refs/heads. Acts
718 * as --all.
719 */
720 public static final RefSpec REFSPEC_PUSH_ALL = new RefSpec(
721 "refs/heads/*:refs/heads/*"); //$NON-NLS-1$
722
723 /** The repository this transport fetches into, or pushes out of. */
724 protected final Repository local;
725
726 /** The URI used to create this transport. */
727 protected final URIish uri;
728
729 /** Name of the upload pack program, if it must be executed. */
730 private String optionUploadPack = RemoteConfig.DEFAULT_UPLOAD_PACK;
731
732 /** Specifications to apply during fetch. */
733 private List<RefSpec> fetch = Collections.emptyList();
734
735 /**
736 * How {@link #fetch(ProgressMonitor, Collection)} should handle tags.
737 * <p>
738 * We default to {@link TagOpt#NO_TAGS} so as to avoid fetching annotated
739 * tags during one-shot fetches used for later merges. This prevents
740 * dragging down tags from repositories that we do not have established
741 * tracking branches for. If we do not track the source repository, we most
742 * likely do not care about any tags it publishes.
743 */
744 private TagOpt tagopt = TagOpt.NO_TAGS;
745
746 /** Should fetch request thin-pack if remote repository can produce it. */
747 private boolean fetchThin = DEFAULT_FETCH_THIN;
748
749 /** Name of the receive pack program, if it must be executed. */
750 private String optionReceivePack = RemoteConfig.DEFAULT_RECEIVE_PACK;
751
752 /** Specifications to apply during push. */
753 private List<RefSpec> push = Collections.emptyList();
754
755 /** Should push produce thin-pack when sending objects to remote repository. */
756 private boolean pushThin = DEFAULT_PUSH_THIN;
757
758 /** Should push be all-or-nothing atomic behavior? */
759 private boolean pushAtomic;
760
761 /** Should push just check for operation result, not really push. */
762 private boolean dryRun;
763
764 /** Should an incoming (fetch) transfer validate objects? */
765 private ObjectChecker objectChecker;
766
767 /** Should refs no longer on the source be pruned from the destination? */
768 private boolean removeDeletedRefs;
769
770 private FilterSpec filterSpec = FilterSpec.NO_FILTER;
771
772 /** Timeout in seconds to wait before aborting an IO read or write. */
773 private int timeout;
774
775 /** Pack configuration used by this transport to make pack file. */
776 private PackConfig packConfig;
777
778 /** Assists with authentication the connection. */
779 private CredentialsProvider credentialsProvider;
780
781 /** The option strings associated with the push operation. */
782 private List<String> pushOptions;
783
784 private PrintStream hookOutRedirect;
785
786 private PrePushHook prePush;
787
788 private Integer depth;
789
790 private Instant deepenSince;
791
792 private List<String> deepenNots = new ArrayList<>();
793
794 @Nullable
795 TransferConfig.ProtocolVersion protocol;
796
797 /**
798 * Create a new transport instance.
799 *
800 * @param local
801 * the repository this instance will fetch into, or push out of.
802 * This must be the repository passed to
803 * {@link #open(Repository, URIish)}.
804 * @param uri
805 * the URI used to access the remote repository. This must be the
806 * URI passed to {@link #open(Repository, URIish)}.
807 */
808 protected Transport(Repository local, URIish uri) {
809 final TransferConfig tc = local.getConfig().get(TransferConfig.KEY);
810 this.local = local;
811 this.uri = uri;
812 this.protocol = tc.protocolVersion;
813 this.objectChecker = tc.newObjectChecker();
814 this.credentialsProvider = CredentialsProvider.getDefault();
815 prePush = Hooks.prePush(local, hookOutRedirect);
816 }
817
818 /**
819 * Create a minimal transport instance not tied to a single repository.
820 *
821 * @param uri
822 * a {@link org.eclipse.jgit.transport.URIish} object.
823 */
824 protected Transport(URIish uri) {
825 this.uri = uri;
826 this.local = null;
827 this.objectChecker = new ObjectChecker();
828 this.credentialsProvider = CredentialsProvider.getDefault();
829 }
830
831 /**
832 * Get the URI this transport connects to.
833 * <p>
834 * Each transport instance connects to at most one URI at any point in time.
835 *
836 * @return the URI describing the location of the remote repository.
837 */
838 public URIish getURI() {
839 return uri;
840 }
841
842 /**
843 * Get the name of the remote executable providing upload-pack service.
844 *
845 * @return typically "git-upload-pack".
846 */
847 public String getOptionUploadPack() {
848 return optionUploadPack;
849 }
850
851 /**
852 * Set the name of the remote executable providing upload-pack services.
853 *
854 * @param where
855 * name of the executable.
856 */
857 public void setOptionUploadPack(String where) {
858 if (where != null && where.length() > 0)
859 optionUploadPack = where;
860 else
861 optionUploadPack = RemoteConfig.DEFAULT_UPLOAD_PACK;
862 }
863
864 /**
865 * Get the description of how annotated tags should be treated during fetch.
866 *
867 * @return option indicating the behavior of annotated tags in fetch.
868 */
869 public TagOpt getTagOpt() {
870 return tagopt;
871 }
872
873 /**
874 * Set the description of how annotated tags should be treated on fetch.
875 *
876 * @param option
877 * method to use when handling annotated tags.
878 */
879 public void setTagOpt(TagOpt option) {
880 tagopt = option != null ? option : TagOpt.AUTO_FOLLOW;
881 }
882
883 /**
884 * Default setting is: {@link #DEFAULT_FETCH_THIN}
885 *
886 * @return true if fetch should request thin-pack when possible; false
887 * otherwise
888 * @see PackTransport
889 */
890 public boolean isFetchThin() {
891 return fetchThin;
892 }
893
894 /**
895 * Set the thin-pack preference for fetch operation. Default setting is:
896 * {@link #DEFAULT_FETCH_THIN}
897 *
898 * @param fetchThin
899 * true when fetch should request thin-pack when possible; false
900 * when it shouldn't
901 * @see PackTransport
902 */
903 public void setFetchThin(boolean fetchThin) {
904 this.fetchThin = fetchThin;
905 }
906
907 /**
908 * Whether fetch will verify if received objects are formatted correctly.
909 *
910 * @return true if fetch will verify received objects are formatted
911 * correctly. Validating objects requires more CPU time on the
912 * client side of the connection.
913 */
914 public boolean isCheckFetchedObjects() {
915 return getObjectChecker() != null;
916 }
917
918 /**
919 * Configure if checking received objects is enabled
920 *
921 * @param check
922 * true to enable checking received objects; false to assume all
923 * received objects are valid.
924 * @see #setObjectChecker(ObjectChecker)
925 */
926 public void setCheckFetchedObjects(boolean check) {
927 if (check && objectChecker == null)
928 setObjectChecker(new ObjectChecker());
929 else if (!check && objectChecker != null)
930 setObjectChecker(null);
931 }
932
933 /**
934 * Get configured object checker for received objects
935 *
936 * @return configured object checker for received objects, or null.
937 * @since 3.6
938 */
939 public ObjectChecker getObjectChecker() {
940 return objectChecker;
941 }
942
943 /**
944 * Set the object checker to verify each received object with
945 *
946 * @param impl
947 * if non-null the object checking instance to verify each
948 * received object with; null to disable object checking.
949 * @since 3.6
950 */
951 public void setObjectChecker(ObjectChecker impl) {
952 objectChecker = impl;
953 }
954
955 /**
956 * Default setting is:
957 * {@link org.eclipse.jgit.transport.RemoteConfig#DEFAULT_RECEIVE_PACK}
958 *
959 * @return remote executable providing receive-pack service for pack
960 * transports.
961 * @see PackTransport
962 */
963 public String getOptionReceivePack() {
964 return optionReceivePack;
965 }
966
967 /**
968 * Set remote executable providing receive-pack service for pack transports.
969 * Default setting is:
970 * {@link org.eclipse.jgit.transport.RemoteConfig#DEFAULT_RECEIVE_PACK}
971 *
972 * @param optionReceivePack
973 * remote executable, if null or empty default one is set;
974 */
975 public void setOptionReceivePack(String optionReceivePack) {
976 if (optionReceivePack != null && optionReceivePack.length() > 0)
977 this.optionReceivePack = optionReceivePack;
978 else
979 this.optionReceivePack = RemoteConfig.DEFAULT_RECEIVE_PACK;
980 }
981
982 /**
983 * Default setting is: {@value #DEFAULT_PUSH_THIN}
984 *
985 * @return true if push should produce thin-pack in pack transports
986 * @see PackTransport
987 */
988 public boolean isPushThin() {
989 return pushThin;
990 }
991
992 /**
993 * Set thin-pack preference for push operation. Default setting is:
994 * {@value #DEFAULT_PUSH_THIN}
995 *
996 * @param pushThin
997 * true when push should produce thin-pack in pack transports;
998 * false when it shouldn't
999 * @see PackTransport
1000 */
1001 public void setPushThin(boolean pushThin) {
1002 this.pushThin = pushThin;
1003 }
1004
1005 /**
1006 * Default setting is false.
1007 *
1008 * @return true if push requires all-or-nothing atomic behavior.
1009 * @since 4.2
1010 */
1011 public boolean isPushAtomic() {
1012 return pushAtomic;
1013 }
1014
1015 /**
1016 * Request atomic push (all references succeed, or none do).
1017 * <p>
1018 * Server must also support atomic push. If the server does not support the
1019 * feature the push will abort without making changes.
1020 *
1021 * @param atomic
1022 * true when push should be an all-or-nothing operation.
1023 * @see PackTransport
1024 * @since 4.2
1025 */
1026 public void setPushAtomic(boolean atomic) {
1027 this.pushAtomic = atomic;
1028 }
1029
1030 /**
1031 * Whether destination refs should be removed if they no longer exist at the
1032 * source repository.
1033 *
1034 * @return true if destination refs should be removed if they no longer
1035 * exist at the source repository.
1036 */
1037 public boolean isRemoveDeletedRefs() {
1038 return removeDeletedRefs;
1039 }
1040
1041 /**
1042 * Set whether or not to remove refs which no longer exist in the source.
1043 * <p>
1044 * If true, refs at the destination repository (local for fetch, remote for
1045 * push) are deleted if they no longer exist on the source side (remote for
1046 * fetch, local for push).
1047 * <p>
1048 * False by default, as this may cause data to become unreachable, and
1049 * eventually be deleted on the next GC.
1050 *
1051 * @param remove true to remove refs that no longer exist.
1052 */
1053 public void setRemoveDeletedRefs(boolean remove) {
1054 removeDeletedRefs = remove;
1055 }
1056
1057 /**
1058 * @return the blob limit value set with {@link #setFilterBlobLimit} or
1059 * {@link #setFilterSpec(FilterSpec)}, or -1 if no blob limit value
1060 * was set
1061 * @since 5.0
1062 * @deprecated Use {@link #getFilterSpec()} instead
1063 */
1064 @Deprecated
1065 public final long getFilterBlobLimit() {
1066 return filterSpec.getBlobLimit();
1067 }
1068
1069 /**
1070 * @param bytes exclude blobs of size greater than this
1071 * @since 5.0
1072 * @deprecated Use {@link #setFilterSpec(FilterSpec)} instead
1073 */
1074 @Deprecated
1075 public final void setFilterBlobLimit(long bytes) {
1076 setFilterSpec(FilterSpec.withBlobLimit(bytes));
1077 }
1078
1079 /**
1080 * @return the last filter spec set with {@link #setFilterSpec(FilterSpec)},
1081 * or {@link FilterSpec#NO_FILTER} if it was never invoked.
1082 * @since 5.4
1083 */
1084 public final FilterSpec getFilterSpec() {
1085 return filterSpec;
1086 }
1087
1088 /**
1089 * @param filter a new filter to use for this transport
1090 * @since 5.4
1091 */
1092 public final void setFilterSpec(@NonNull FilterSpec filter) {
1093 filterSpec = requireNonNull(filter);
1094 }
1095
1096
1097 /**
1098 * Retrieves the depth for a shallow clone.
1099 *
1100 * @return the depth, or {@code null} if none set
1101 * @since 6.3
1102 */
1103 public final Integer getDepth() {
1104 return depth;
1105 }
1106
1107 /**
1108 * Limits fetching to the specified number of commits from the tip of each
1109 * remote branch history.
1110 *
1111 * @param depth
1112 * the depth
1113 * @since 6.3
1114 */
1115 public final void setDepth(int depth) {
1116 if (depth < 1) {
1117 throw new IllegalArgumentException(JGitText.get().depthMustBeAt1);
1118 }
1119 this.depth = Integer.valueOf(depth);
1120 }
1121
1122 /**
1123 * Limits fetching to the specified number of commits from the tip of each
1124 * remote branch history.
1125 *
1126 * @param depth
1127 * the depth, or {@code null} to unset the depth
1128 * @since 6.3
1129 */
1130 public final void setDepth(Integer depth) {
1131 if (depth != null && depth.intValue() < 1) {
1132 throw new IllegalArgumentException(JGitText.get().depthMustBeAt1);
1133 }
1134 this.depth = depth;
1135 }
1136
1137 /**
1138 * @return the deepen-since for a shallow clone
1139 * @since 6.3
1140 */
1141 public final Instant getDeepenSince() {
1142 return deepenSince;
1143 }
1144
1145 /**
1146 * Deepen or shorten the history of a shallow repository to include all reachable commits after a specified time.
1147 *
1148 * @param deepenSince the deepen-since. Must not be {@code null}
1149 * @since 6.3
1150 */
1151 public final void setDeepenSince(@NonNull Instant deepenSince) {
1152 this.deepenSince = deepenSince;
1153 }
1154
1155 /**
1156 * @return the deepen-not for a shallow clone
1157 * @since 6.3
1158 */
1159 public final List<String> getDeepenNots() {
1160 return deepenNots;
1161 }
1162
1163 /**
1164 * Deepen or shorten the history of a shallow repository to exclude commits reachable from a specified remote branch or tag.
1165 *
1166 * @param deepenNots the deepen-not. Must not be {@code null}
1167 * @since 6.3
1168 */
1169 public final void setDeepenNots(@NonNull List<String> deepenNots) {
1170 this.deepenNots = deepenNots;
1171 }
1172
1173 /**
1174 * Apply provided remote configuration on this transport.
1175 *
1176 * @param cfg
1177 * configuration to apply on this transport.
1178 */
1179 public void applyConfig(RemoteConfig cfg) {
1180 setOptionUploadPack(cfg.getUploadPack());
1181 setOptionReceivePack(cfg.getReceivePack());
1182 setTagOpt(cfg.getTagOpt());
1183 fetch = cfg.getFetchRefSpecs();
1184 push = cfg.getPushRefSpecs();
1185 timeout = cfg.getTimeout();
1186 }
1187
1188 /**
1189 * Whether push operation should just check for possible result and not
1190 * really update remote refs
1191 *
1192 * @return true if push operation should just check for possible result and
1193 * not really update remote refs, false otherwise - when push should
1194 * act normally.
1195 */
1196 public boolean isDryRun() {
1197 return dryRun;
1198 }
1199
1200 /**
1201 * Set dry run option for push operation.
1202 *
1203 * @param dryRun
1204 * true if push operation should just check for possible result
1205 * and not really update remote refs, false otherwise - when push
1206 * should act normally.
1207 */
1208 public void setDryRun(boolean dryRun) {
1209 this.dryRun = dryRun;
1210 }
1211
1212 /**
1213 * Get timeout (in seconds) before aborting an IO operation.
1214 *
1215 * @return timeout (in seconds) before aborting an IO operation.
1216 */
1217 public int getTimeout() {
1218 return timeout;
1219 }
1220
1221 /**
1222 * Set the timeout before willing to abort an IO call.
1223 *
1224 * @param seconds
1225 * number of seconds to wait (with no data transfer occurring)
1226 * before aborting an IO read or write operation with this
1227 * remote.
1228 */
1229 public void setTimeout(int seconds) {
1230 timeout = seconds;
1231 }
1232
1233 /**
1234 * Get the configuration used by the pack generator to make packs.
1235 *
1236 * If {@link #setPackConfig(PackConfig)} was previously given null a new
1237 * PackConfig is created on demand by this method using the source
1238 * repository's settings.
1239 *
1240 * @return the pack configuration. Never null.
1241 */
1242 public PackConfig getPackConfig() {
1243 if (packConfig == null)
1244 packConfig = new PackConfig(local);
1245 return packConfig;
1246 }
1247
1248 /**
1249 * Set the configuration used by the pack generator.
1250 *
1251 * @param pc
1252 * configuration controlling packing parameters. If null the
1253 * source repository's settings will be used.
1254 */
1255 public void setPackConfig(PackConfig pc) {
1256 packConfig = pc;
1257 }
1258
1259 /**
1260 * A credentials provider to assist with authentication connections..
1261 *
1262 * @param credentialsProvider
1263 * the credentials provider, or null if there is none
1264 */
1265 public void setCredentialsProvider(CredentialsProvider credentialsProvider) {
1266 this.credentialsProvider = credentialsProvider;
1267 }
1268
1269 /**
1270 * The configured credentials provider.
1271 *
1272 * @return the credentials provider, or null if no credentials provider is
1273 * associated with this transport.
1274 */
1275 public CredentialsProvider getCredentialsProvider() {
1276 return credentialsProvider;
1277 }
1278
1279 /**
1280 * Get the option strings associated with the push operation
1281 *
1282 * @return the option strings associated with the push operation
1283 * @since 4.5
1284 */
1285 public List<String> getPushOptions() {
1286 return pushOptions;
1287 }
1288
1289 /**
1290 * Sets the option strings associated with the push operation.
1291 *
1292 * @param pushOptions
1293 * null if push options are unsupported
1294 * @since 4.5
1295 */
1296 public void setPushOptions(List<String> pushOptions) {
1297 this.pushOptions = pushOptions;
1298 }
1299
1300 /**
1301 * Fetch objects and refs from the remote repository to the local one.
1302 * <p>
1303 * This is a utility function providing standard fetch behavior. Local
1304 * tracking refs associated with the remote repository are automatically
1305 * updated if this transport was created from a
1306 * {@link org.eclipse.jgit.transport.RemoteConfig} with fetch RefSpecs
1307 * defined.
1308 *
1309 * @param monitor
1310 * progress monitor to inform the user about our processing
1311 * activity. Must not be null. Use
1312 * {@link org.eclipse.jgit.lib.NullProgressMonitor} if progress
1313 * updates are not interesting or necessary.
1314 * @param toFetch
1315 * specification of refs to fetch locally. May be null or the
1316 * empty collection to use the specifications from the
1317 * RemoteConfig. May contains regular and negative
1318 * {@link RefSpec}s. Source for each regular RefSpec can't
1319 * be null.
1320 * @return information describing the tracking refs updated.
1321 * @throws org.eclipse.jgit.errors.NotSupportedException
1322 * this transport implementation does not support fetching
1323 * objects.
1324 * @throws org.eclipse.jgit.errors.TransportException
1325 * the remote connection could not be established or object
1326 * copying (if necessary) failed or update specification was
1327 * incorrect.
1328 * @since 5.11
1329 */
1330 public FetchResult fetch(final ProgressMonitor monitor,
1331 Collection<RefSpec> toFetch)
1332 throws NotSupportedException, TransportException {
1333 return fetch(monitor, toFetch, null);
1334 }
1335
1336 /**
1337 * Fetch objects and refs from the remote repository to the local one.
1338 * <p>
1339 * This is a utility function providing standard fetch behavior. Local
1340 * tracking refs associated with the remote repository are automatically
1341 * updated if this transport was created from a
1342 * {@link org.eclipse.jgit.transport.RemoteConfig} with fetch RefSpecs
1343 * defined.
1344 *
1345 * @param monitor
1346 * progress monitor to inform the user about our processing
1347 * activity. Must not be null. Use
1348 * {@link org.eclipse.jgit.lib.NullProgressMonitor} if progress
1349 * updates are not interesting or necessary.
1350 * @param toFetch
1351 * specification of refs to fetch locally. May be null or the
1352 * empty collection to use the specifications from the
1353 * RemoteConfig. May contain regular and negative
1354 * {@link RefSpec}s. Source for each regular RefSpec can't
1355 * be null.
1356 * @param branch
1357 * the initial branch to check out when cloning the repository.
1358 * Can be specified as ref name (<code>refs/heads/master</code>),
1359 * branch name (<code>master</code>) or tag name
1360 * (<code>v1.2.3</code>). The default is to use the branch
1361 * pointed to by the cloned repository's HEAD and can be
1362 * requested by passing {@code null} or <code>HEAD</code>.
1363 * @return information describing the tracking refs updated.
1364 * @throws org.eclipse.jgit.errors.NotSupportedException
1365 * this transport implementation does not support fetching
1366 * objects.
1367 * @throws org.eclipse.jgit.errors.TransportException
1368 * the remote connection could not be established or object
1369 * copying (if necessary) failed or update specification was
1370 * incorrect.
1371 * @since 5.11
1372 */
1373 public FetchResult fetch(final ProgressMonitor monitor,
1374 Collection<RefSpec> toFetch, String branch)
1375 throws NotSupportedException,
1376 TransportException {
1377 if (toFetch == null || toFetch.isEmpty()) {
1378 // If the caller did not ask for anything use the defaults.
1379 //
1380 if (fetch.isEmpty())
1381 throw new TransportException(JGitText.get().nothingToFetch);
1382 toFetch = fetch;
1383 } else if (!fetch.isEmpty()) {
1384 // If the caller asked for something specific without giving
1385 // us the local tracking branch see if we can update any of
1386 // the local tracking branches without incurring additional
1387 // object transfer overheads.
1388 //
1389 final Collection<RefSpec> tmp = new ArrayList<>(toFetch);
1390 for (RefSpec requested : toFetch) {
1391 final String reqSrc = requested.getSource();
1392 for (RefSpec configured : fetch) {
1393 final String cfgSrc = configured.getSource();
1394 final String cfgDst = configured.getDestination();
1395 if (cfgSrc.equals(reqSrc) && cfgDst != null) {
1396 tmp.add(configured);
1397 break;
1398 }
1399 }
1400 }
1401 toFetch = tmp;
1402 }
1403
1404 final FetchResult result = new FetchResult();
1405 new FetchProcess(this, toFetch).execute(monitor, result, branch);
1406
1407 local.autoGC(monitor);
1408
1409 return result;
1410 }
1411
1412 /**
1413 * Push objects and refs from the local repository to the remote one.
1414 * <p>
1415 * This is a utility function providing standard push behavior. It updates
1416 * remote refs and send there necessary objects according to remote ref
1417 * update specification. After successful remote ref update, associated
1418 * locally stored tracking branch is updated if set up accordingly. Detailed
1419 * operation result is provided after execution.
1420 * <p>
1421 * For setting up remote ref update specification from ref spec, see helper
1422 * method {@link #findRemoteRefUpdatesFor(Collection)}, predefined refspecs
1423 * ({@link #REFSPEC_TAGS}, {@link #REFSPEC_PUSH_ALL}) or consider using
1424 * directly {@link org.eclipse.jgit.transport.RemoteRefUpdate} for more
1425 * possibilities.
1426 * <p>
1427 * When {@link #isDryRun()} is true, result of this operation is just
1428 * estimation of real operation result, no real action is performed.
1429 *
1430 * @see RemoteRefUpdate
1431 * @param monitor
1432 * progress monitor to inform the user about our processing
1433 * activity. Must not be null. Use
1434 * {@link org.eclipse.jgit.lib.NullProgressMonitor} if progress
1435 * updates are not interesting or necessary.
1436 * @param toPush
1437 * specification of refs to push. May be null or the empty
1438 * collection to use the specifications from the RemoteConfig
1439 * converted by {@link #findRemoteRefUpdatesFor(Collection)}. No
1440 * more than 1 RemoteRefUpdate with the same remoteName is
1441 * allowed. These objects are modified during this call.
1442 * @param out
1443 * output stream to write messages to
1444 * @return information about results of remote refs updates, tracking refs
1445 * updates and refs advertised by remote repository.
1446 * @throws org.eclipse.jgit.errors.NotSupportedException
1447 * this transport implementation does not support pushing
1448 * objects.
1449 * @throws org.eclipse.jgit.errors.TransportException
1450 * the remote connection could not be established or object
1451 * copying (if necessary) failed at I/O or protocol level or
1452 * update specification was incorrect.
1453 * @since 3.0
1454 */
1455 public PushResult push(final ProgressMonitor monitor,
1456 Collection<RemoteRefUpdate> toPush, OutputStream out)
1457 throws NotSupportedException,
1458 TransportException {
1459 if (toPush == null || toPush.isEmpty()) {
1460 // If the caller did not ask for anything use the defaults.
1461 try {
1462 toPush = findRemoteRefUpdatesFor(push);
1463 } catch (final IOException e) {
1464 throw new TransportException(MessageFormat.format(
1465 JGitText.get().problemWithResolvingPushRefSpecsLocally, e.getMessage()), e);
1466 }
1467 if (toPush.isEmpty())
1468 throw new TransportException(JGitText.get().nothingToPush);
1469 }
1470
1471 final PushProcess pushProcess = new PushProcess(this, toPush, prePush,
1472 out);
1473 return pushProcess.execute(monitor);
1474 }
1475
1476 /**
1477 * Push objects and refs from the local repository to the remote one.
1478 * <p>
1479 * This is a utility function providing standard push behavior. It updates
1480 * remote refs and sends necessary objects according to remote ref update
1481 * specification. After successful remote ref update, associated locally
1482 * stored tracking branch is updated if set up accordingly. Detailed
1483 * operation result is provided after execution.
1484 * <p>
1485 * For setting up remote ref update specification from ref spec, see helper
1486 * method {@link #findRemoteRefUpdatesFor(Collection)}, predefined refspecs
1487 * ({@link #REFSPEC_TAGS}, {@link #REFSPEC_PUSH_ALL}) or consider using
1488 * directly {@link org.eclipse.jgit.transport.RemoteRefUpdate} for more
1489 * possibilities.
1490 * <p>
1491 * When {@link #isDryRun()} is true, result of this operation is just
1492 * estimation of real operation result, no real action is performed.
1493 *
1494 * @see RemoteRefUpdate
1495 * @param monitor
1496 * progress monitor to inform the user about our processing
1497 * activity. Must not be null. Use
1498 * {@link org.eclipse.jgit.lib.NullProgressMonitor} if progress
1499 * updates are not interesting or necessary.
1500 * @param toPush
1501 * specification of refs to push. May be null or the empty
1502 * collection to use the specifications from the RemoteConfig
1503 * converted by {@link #findRemoteRefUpdatesFor(Collection)}. No
1504 * more than 1 RemoteRefUpdate with the same remoteName is
1505 * allowed. These objects are modified during this call.
1506 * @return information about results of remote refs updates, tracking refs
1507 * updates and refs advertised by remote repository.
1508 * @throws org.eclipse.jgit.errors.NotSupportedException
1509 * this transport implementation does not support pushing
1510 * objects.
1511 * @throws org.eclipse.jgit.errors.TransportException
1512 * the remote connection could not be established or object
1513 * copying (if necessary) failed at I/O or protocol level or
1514 * update specification was incorrect.
1515 */
1516 public PushResult push(final ProgressMonitor monitor,
1517 Collection<RemoteRefUpdate> toPush) throws NotSupportedException,
1518 TransportException {
1519 return push(monitor, toPush, null);
1520 }
1521
1522 /**
1523 * Convert push remote refs update specification from
1524 * {@link org.eclipse.jgit.transport.RefSpec} form to
1525 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands
1526 * wildcards by matching source part to local refs. expectedOldObjectId in
1527 * RemoteRefUpdate is always set as null. Tracking branch is configured if
1528 * RefSpec destination matches source of any fetch ref spec for this
1529 * transport remote configuration.
1530 * <p>
1531 * Conversion is performed for context of this transport (database, fetch
1532 * specifications).
1533 *
1534 * @param specs
1535 * collection of RefSpec to convert.
1536 * @return collection of set up
1537 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}.
1538 * @throws java.io.IOException
1539 * when problem occurred during conversion or specification set
1540 * up: most probably, missing objects or refs.
1541 */
1542 public Collection<RemoteRefUpdate> findRemoteRefUpdatesFor(
1543 final Collection<RefSpec> specs) throws IOException {
1544 return findRemoteRefUpdatesFor(local, specs, Collections.emptyMap(),
1545 fetch);
1546 }
1547
1548 /**
1549 * Convert push remote refs update specification from
1550 * {@link org.eclipse.jgit.transport.RefSpec} form to
1551 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands
1552 * wildcards by matching source part to local refs. expectedOldObjectId in
1553 * RemoteRefUpdate is set according to leases. Tracking branch is configured
1554 * if RefSpec destination matches source of any fetch ref spec for this
1555 * transport remote configuration.
1556 * <p>
1557 * Conversion is performed for context of this transport (database, fetch
1558 * specifications).
1559 *
1560 * @param specs
1561 * collection of RefSpec to convert.
1562 * @param leases
1563 * map from ref to lease (containing expected old object id)
1564 * @return collection of set up
1565 * {@link org.eclipse.jgit.transport.RemoteRefUpdate}.
1566 * @throws java.io.IOException
1567 * when problem occurred during conversion or specification set
1568 * up: most probably, missing objects or refs.
1569 * @since 4.7
1570 */
1571 public Collection<RemoteRefUpdate> findRemoteRefUpdatesFor(
1572 final Collection<RefSpec> specs,
1573 final Map<String, RefLeaseSpec> leases) throws IOException {
1574 return findRemoteRefUpdatesFor(local, specs, leases,
1575 fetch);
1576 }
1577
1578 /**
1579 * Begins a new connection for fetching from the remote repository.
1580 * <p>
1581 * If the transport has no local repository, the fetch connection can only
1582 * be used for reading remote refs.
1583 *
1584 * @return a fresh connection to fetch from the remote repository.
1585 * @throws org.eclipse.jgit.errors.NotSupportedException
1586 * the implementation does not support fetching.
1587 * @throws org.eclipse.jgit.errors.TransportException
1588 * the remote connection could not be established.
1589 */
1590 public abstract FetchConnection openFetch() throws NotSupportedException,
1591 TransportException;
1592
1593 /**
1594 * Begins a new connection for fetching from the remote repository.
1595 * <p>
1596 * If the transport has no local repository, the fetch connection can only
1597 * be used for reading remote refs.
1598 * </p>
1599 * <p>
1600 * If the server supports git protocol V2, the {@link RefSpec}s and the
1601 * additional patterns, if any, are used to restrict the server's ref
1602 * advertisement to matching refs only.
1603 * </p>
1604 * <p>
1605 * Transports that want to support git protocol V2 <em>must</em> override
1606 * this; the default implementation ignores its arguments and calls
1607 * {@link #openFetch()}.
1608 * </p>
1609 *
1610 * @param refSpecs
1611 * that will be fetched via
1612 * {@link FetchConnection#fetch(ProgressMonitor, Collection, java.util.Set, OutputStream)} later
1613 * @param additionalPatterns
1614 * that will be set as ref prefixes if the server supports git
1615 * protocol V2; {@code null} values are ignored
1616 *
1617 * @return a fresh connection to fetch from the remote repository.
1618 * @throws org.eclipse.jgit.errors.NotSupportedException
1619 * the implementation does not support fetching.
1620 * @throws org.eclipse.jgit.errors.TransportException
1621 * the remote connection could not be established.
1622 * @since 5.11
1623 */
1624 public FetchConnection openFetch(Collection<RefSpec> refSpecs,
1625 String... additionalPatterns)
1626 throws NotSupportedException, TransportException {
1627 return openFetch();
1628 }
1629
1630 /**
1631 * Begins a new connection for pushing into the remote repository.
1632 *
1633 * @return a fresh connection to push into the remote repository.
1634 * @throws org.eclipse.jgit.errors.NotSupportedException
1635 * the implementation does not support pushing.
1636 * @throws org.eclipse.jgit.errors.TransportException
1637 * the remote connection could not be established
1638 */
1639 public abstract PushConnection openPush() throws NotSupportedException,
1640 TransportException;
1641
1642 /**
1643 * {@inheritDoc}
1644 * <p>
1645 * Close any resources used by this transport.
1646 * <p>
1647 * If the remote repository is contacted by a network socket this method
1648 * must close that network socket, disconnecting the two peers. If the
1649 * remote repository is actually local (same system) this method must close
1650 * any open file handles used to read the "remote" repository.
1651 * <p>
1652 * {@code AutoClosable.close()} declares that it throws {@link Exception}.
1653 * Implementers shouldn't throw checked exceptions. This override narrows
1654 * the signature to prevent them from doing so.
1655 */
1656 @Override
1657 public abstract void close();
1658 }