What exactly does `pod repo update` do?

As per the documentation pod repo update updates the spec repos located at ~/.cocoapods/repos in your home folder.

Updates the local clone of the spec-repo NAME. If NAME is omitted this will update all spec-repos in ~/.cocoapods/repos.

The repo is basically a list of all pods and versions available. I have just encountered an error in our CI builds because the repo did not include a spec for a library I have just added. By running pod repo update it now knows of this newer version and can continue to install it.

So to answer your question.. Running pod repo update in your documents folder will not do anything in that folder. It will update its pod spec references in your ~/.cocoapods/repos folder only.

The main Specs repo is nothing but a list of ALL PodSpecs. A PodSpec is:

A specification describes a version of Pod library. It includes details about where the source should be fetched from [which tag or commit or branch], what files to use, the build settings to apply, and other general metadata such as its name, version, and description.

The specs directory is nothing but a list of all distinct PodSpecs. Each version of the PodSpec is under a tag directory. The repo doesn't contain the pod itself. The repo contains the PodSpec. The PodSpec gives the location of the repo and a bunch of other meta data⚡︎

spec.source = { :git => 'https://github.com/tonymillion/Reachability.git', :tag => 'v3.1.0' }

When you do pod repo update, you're pulling the latest PodSpecs (not the actual pod) from https://github.com/CocoaPods/Specs. If you want to only update an individual pod source, then just do pod repo update [NAME]

Cocoapods/Specs master repo:

The list of some Alamofire PodSpecs

A single PodSpec 4.7.3:

⚡︎: PodSpec: A specification describes a version of Pod library. Itincludes details about where the source should be fetched from, whatfiles to use, the build settings to apply, and other general metadatasuch as its name, version, and description.

Your actual project pulls in the code through either pod update or pod install then the physical files get downloaded to your mac and copied for your project.