Allow arbitrary reachability roots to be fed in

Instead of only traversing objects starting at references, allow the
user to specify explicit Git objects via the command line. In that
case, the traversal includes objects reachable from those objects.

Author: mhagger

git-sizer.go

@@ -20,7 +20,9 @@ import (
 	"github.com/github/git-sizer/sizes"
 )
 
-const usage = `usage: git-sizer [OPTS]
+const usage = `usage: git-sizer [OPTS] [ROOT...]
+
+ Scan objects in your Git repository and emit statistics about them.
 
       --threshold THRESHOLD    minimum level of concern (i.e., number of stars)
                                that should be reported. Default:
@@ -46,12 +48,29 @@ const usage = `usage: git-sizer [OPTS]
                                be set via gitconfig: 'sizer.progress'.
       --version                only report the git-sizer version number
 
+ Object selection:
+
+ git-sizer traverses through your Git history to find objects to
+ process. By default, it processes all objects that are reachable from
+ any reference. You can tell it to process only some of your
+ references; see "Reference selection" below.
+
+ If explicit ROOTs are specified on the command line, each one should
+ be a string that 'git rev-parse' can convert into a single Git object
+ ID, like 'main', 'main~:src', or an abbreviated SHA-1. See
+ git-rev-parse(1) for details. In that case, git-sizer also treats
+ those objects as starting points for its traversal, and also includes
+ the Git objects that are reachable from those roots in the analysis.
+
+ As a special case, if one or more ROOTs are specified on the command
+ line but _no_ reference selection options, then _only_ the specified
+ ROOTs are traversed, and no references.
+
  Reference selection:
 
- By default, git-sizer processes all Git objects that are reachable
- from any reference. The following options can be used to limit which
- references to process. The last rule matching a reference determines
- whether that reference is processed.
+ The following options can be used to limit which references to
+ process. The last rule matching a reference determines whether that
+ reference is processed.
 
       --[no-]branches          process [don't process] branches
       --[no-]tags              process [don't process] tags
@@ -220,10 +239,6 @@ func mainImplementation(ctx context.Context, stdout, stderr io.Writer, args []st
 		return nil
 	}
 
-	if len(flags.Args()) != 0 {
-		return errors.New("excess arguments")
-	}
-
 	if repoErr != nil {
 		return fmt.Errorf("couldn't open Git repository: %w", repoErr)
 	}
@@ -277,7 +292,7 @@ func mainImplementation(ctx context.Context, stdout, stderr io.Writer, args []st
 		progress = v
 	}
 
-	rg, err := rgb.Finish()
+	rg, err := rgb.Finish(len(flags.Args()) == 0)
 	if err != nil {
 		return err
 	}
@@ -297,8 +312,21 @@ func mainImplementation(ctx context.Context, stdout, stderr io.Writer, args []st
 		return fmt.Errorf("determining which reference to scan: %w", err)
 	}
 
+	roots := make([]sizes.Root, 0, len(refRoots)+len(flags.Args()))
+	for _, refRoot := range refRoots {
+		roots = append(roots, refRoot)
+	}
+
+	for _, arg := range flags.Args() {
+		oid, err := repo.ResolveObject(arg)
+		if err != nil {
+			return fmt.Errorf("resolving command-line argument %q: %w", arg, err)
+		}
+		roots = append(roots, sizes.NewExplicitRoot(arg, oid))
+	}
+
 	historySize, err := sizes.ScanRepositoryUsingGraph(
-		ctx, repo, refRoots, nameStyle, progressMeter,
+		ctx, repo, roots, nameStyle, progressMeter,
 	)
 	if err != nil {
 		return fmt.Errorf("error scanning repository: %w", err)

git/obj_resolver.go

@@ -0,0 +1,20 @@
+package git
+
+import (
+	"bytes"
+	"fmt"
+)
+
+func (repo *Repository) ResolveObject(name string) (OID, error) {
+	cmd := repo.GitCommand("rev-parse", "--verify", "--end-of-options", name)
+	output, err := cmd.Output()
+	if err != nil {
+		return NullOID, fmt.Errorf("resolving object %q: %w", name, err)
+	}
+	oidString := string(bytes.TrimSpace(output))
+	oid, err := NewOID(oidString)
+	if err != nil {
+		return NullOID, fmt.Errorf("parsing output %q from 'rev-parse': %w", oidString, err)
+	}
+	return oid, nil
+}

git/ref_filter.go

@@ -83,15 +83,23 @@ func (_ allReferencesFilter) Filter(_ string) bool {
 
 var AllReferencesFilter allReferencesFilter
 
+type noReferencesFilter struct{}
+
+func (_ noReferencesFilter) Filter(_ string) bool {
+	return false
+}
+
+var NoReferencesFilter noReferencesFilter
+
 // PrefixFilter returns a `ReferenceFilter` that matches references
 // whose names start with the specified `prefix`, which must match at
 // a component boundary. For example,
 //
-// * Prefix "refs/foo" matches "refs/foo" and "refs/foo/bar" but not
-//   "refs/foobar".
+//   - Prefix "refs/foo" matches "refs/foo" and "refs/foo/bar" but not
+//     "refs/foobar".
 //
-// * Prefix "refs/foo/" matches "refs/foo/bar" but not "refs/foo" or
-//   "refs/foobar".
+//   - Prefix "refs/foo/" matches "refs/foo/bar" but not "refs/foo" or
+//     "refs/foobar".
 func PrefixFilter(prefix string) ReferenceFilter {
 	if prefix == "" {
 		return AllReferencesFilter

git_sizer_test.go

@@ -567,54 +567,112 @@ func TestBomb(t *testing.T) {
 
 	repo := testRepo.Repository(t)
 
-	refRoots, err := sizes.CollectReferences(ctx, repo, refGrouper{})
-	require.NoError(t, err)
+	t.Run("full", func(t *testing.T) {
+		refRoots, err := sizes.CollectReferences(ctx, repo, refGrouper{})
+		require.NoError(t, err)
 
-	h, err := sizes.ScanRepositoryUsingGraph(
-		ctx, repo,
-		refRoots, sizes.NameStyleFull, meter.NoProgressMeter,
-	)
-	require.NoError(t, err)
+		roots := make([]sizes.Root, 0, len(refRoots))
+		for _, refRoot := range refRoots {
+			roots = append(roots, refRoot)
+		}
+
+		h, err := sizes.ScanRepositoryUsingGraph(
+			ctx, repo, roots, sizes.NameStyleFull, meter.NoProgressMeter,
+		)
+		require.NoError(t, err)
+
+		assert.Equal(t, counts.Count32(1), h.UniqueCommitCount, "unique commit count")
+		assert.Equal(t, counts.Count64(172), h.UniqueCommitSize, "unique commit size")
+		assert.Equal(t, counts.Count32(172), h.MaxCommitSize, "max commit size")
+		assert.Equal(t, "refs/heads/master", h.MaxCommitSizeCommit.BestPath(), "max commit size commit")
+		assert.Equal(t, counts.Count32(1), h.MaxHistoryDepth, "max history depth")
+		assert.Equal(t, counts.Count32(0), h.MaxParentCount, "max parent count")
+		assert.Equal(t, "refs/heads/master", h.MaxParentCountCommit.BestPath(), "max parent count commit")
+
+		assert.Equal(t, counts.Count32(10), h.UniqueTreeCount, "unique tree count")
+		assert.Equal(t, counts.Count64(2910), h.UniqueTreeSize, "unique tree size")
+		assert.Equal(t, counts.Count64(100), h.UniqueTreeEntries, "unique tree entries")
+		assert.Equal(t, counts.Count32(10), h.MaxTreeEntries, "max tree entries")
+		assert.Equal(t, "refs/heads/master:d0/d0/d0/d0/d0/d0/d0/d0/d0", h.MaxTreeEntriesTree.BestPath(), "max tree entries tree")
+
+		assert.Equal(t, counts.Count32(1), h.UniqueBlobCount, "unique blob count")
+		assert.Equal(t, counts.Count64(6), h.UniqueBlobSize, "unique blob size")
+		assert.Equal(t, counts.Count32(6), h.MaxBlobSize, "max blob size")
+		assert.Equal(t, "refs/heads/master:d0/d0/d0/d0/d0/d0/d0/d0/d0/f0", h.MaxBlobSizeBlob.BestPath(), "max blob size blob")
+
+		assert.Equal(t, counts.Count32(0), h.UniqueTagCount, "unique tag count")
+		assert.Equal(t, counts.Count32(0), h.MaxTagDepth, "max tag depth")
+
+		assert.Equal(t, counts.Count32(1), h.ReferenceCount, "reference count")
+
+		assert.Equal(t, counts.Count32(10), h.MaxPathDepth, "max path depth")
+		assert.Equal(t, "refs/heads/master^{tree}", h.MaxPathDepthTree.BestPath(), "max path depth tree")
+		assert.Equal(t, counts.Count32(29), h.MaxPathLength, "max path length")
+		assert.Equal(t, "refs/heads/master^{tree}", h.MaxPathLengthTree.BestPath(), "max path length tree")
+
+		assert.Equal(t, counts.Count32((pow(10, 10)-1)/(10-1)), h.MaxExpandedTreeCount, "max expanded tree count")
+		assert.Equal(t, "refs/heads/master^{tree}", h.MaxExpandedTreeCountTree.BestPath(), "max expanded tree count tree")
+		assert.Equal(t, counts.Count32(0xffffffff), h.MaxExpandedBlobCount, "max expanded blob count")
+		assert.Equal(t, "refs/heads/master^{tree}", h.MaxExpandedBlobCountTree.BestPath(), "max expanded blob count tree")
+		assert.Equal(t, counts.Count64(6*pow(10, 10)), h.MaxExpandedBlobSize, "max expanded blob size")
+		assert.Equal(t, "refs/heads/master^{tree}", h.MaxExpandedBlobSizeTree.BestPath(), "max expanded blob size tree")
+		assert.Equal(t, counts.Count32(0), h.MaxExpandedLinkCount, "max expanded link count")
+		assert.Nil(t, h.MaxExpandedLinkCountTree, "max expanded link count tree")
+		assert.Equal(t, counts.Count32(0), h.MaxExpandedSubmoduleCount, "max expanded submodule count")
+		assert.Nil(t, h.MaxExpandedSubmoduleCountTree, "max expanded submodule count tree")
+	})
+
+	t.Run("partial", func(t *testing.T) {
+		name := "master:d0/d0"
+		oid, err := repo.ResolveObject(name)
+		require.NoError(t, err)
+		roots := []sizes.Root{sizes.NewExplicitRoot(name, oid)}
 
-	assert.Equal(t, counts.Count32(1), h.UniqueCommitCount, "unique commit count")
-	assert.Equal(t, counts.Count64(172), h.UniqueCommitSize, "unique commit size")
-	assert.Equal(t, counts.Count32(172), h.MaxCommitSize, "max commit size")
-	assert.Equal(t, "refs/heads/master", h.MaxCommitSizeCommit.Path(), "max commit size commit")
-	assert.Equal(t, counts.Count32(1), h.MaxHistoryDepth, "max history depth")
-	assert.Equal(t, counts.Count32(0), h.MaxParentCount, "max parent count")
-	assert.Equal(t, "refs/heads/master", h.MaxParentCountCommit.Path(), "max parent count commit")
-
-	assert.Equal(t, counts.Count32(10), h.UniqueTreeCount, "unique tree count")
-	assert.Equal(t, counts.Count64(2910), h.UniqueTreeSize, "unique tree size")
-	assert.Equal(t, counts.Count64(100), h.UniqueTreeEntries, "unique tree entries")
-	assert.Equal(t, counts.Count32(10), h.MaxTreeEntries, "max tree entries")
-	assert.Equal(t, "refs/heads/master:d0/d0/d0/d0/d0/d0/d0/d0/d0", h.MaxTreeEntriesTree.Path(), "max tree entries tree")
-
-	assert.Equal(t, counts.Count32(1), h.UniqueBlobCount, "unique blob count")
-	assert.Equal(t, counts.Count64(6), h.UniqueBlobSize, "unique blob size")
-	assert.Equal(t, counts.Count32(6), h.MaxBlobSize, "max blob size")
-	assert.Equal(t, "refs/heads/master:d0/d0/d0/d0/d0/d0/d0/d0/d0/f0", h.MaxBlobSizeBlob.Path(), "max blob size blob")
-
-	assert.Equal(t, counts.Count32(0), h.UniqueTagCount, "unique tag count")
-	assert.Equal(t, counts.Count32(0), h.MaxTagDepth, "max tag depth")
-
-	assert.Equal(t, counts.Count32(1), h.ReferenceCount, "reference count")
-
-	assert.Equal(t, counts.Count32(10), h.MaxPathDepth, "max path depth")
-	assert.Equal(t, "refs/heads/master^{tree}", h.MaxPathDepthTree.Path(), "max path depth tree")
-	assert.Equal(t, counts.Count32(29), h.MaxPathLength, "max path length")
-	assert.Equal(t, "refs/heads/master^{tree}", h.MaxPathLengthTree.Path(), "max path length tree")
-
-	assert.Equal(t, counts.Count32((pow(10, 10)-1)/(10-1)), h.MaxExpandedTreeCount, "max expanded tree count")
-	assert.Equal(t, "refs/heads/master^{tree}", h.MaxExpandedTreeCountTree.Path(), "max expanded tree count tree")
-	assert.Equal(t, counts.Count32(0xffffffff), h.MaxExpandedBlobCount, "max expanded blob count")
-	assert.Equal(t, "refs/heads/master^{tree}", h.MaxExpandedBlobCountTree.Path(), "max expanded blob count tree")
-	assert.Equal(t, counts.Count64(6*pow(10, 10)), h.MaxExpandedBlobSize, "max expanded blob size")
-	assert.Equal(t, "refs/heads/master^{tree}", h.MaxExpandedBlobSizeTree.Path(), "max expanded blob size tree")
-	assert.Equal(t, counts.Count32(0), h.MaxExpandedLinkCount, "max expanded link count")
-	assert.Nil(t, h.MaxExpandedLinkCountTree, "max expanded link count tree")
-	assert.Equal(t, counts.Count32(0), h.MaxExpandedSubmoduleCount, "max expanded submodule count")
-	assert.Nil(t, h.MaxExpandedSubmoduleCountTree, "max expanded submodule count tree")
+		h, err := sizes.ScanRepositoryUsingGraph(
+			ctx, repo, roots, sizes.NameStyleFull, meter.NoProgressMeter,
+		)
+		require.NoError(t, err)
+
+		assert.Equal(t, counts.Count32(0), h.UniqueCommitCount, "unique commit count")
+		assert.Equal(t, counts.Count64(0), h.UniqueCommitSize, "unique commit size")
+		assert.Equal(t, counts.Count32(0), h.MaxCommitSize, "max commit size")
+		assert.Nil(t, h.MaxCommitSizeCommit)
+		assert.Equal(t, counts.Count32(0), h.MaxHistoryDepth, "max history depth")
+		assert.Equal(t, counts.Count32(0), h.MaxParentCount, "max parent count")
+		assert.Nil(t, h.MaxParentCountCommit, "max parent count commit")
+
+		assert.Equal(t, counts.Count32(8), h.UniqueTreeCount, "unique tree count")
+		assert.Equal(t, counts.Count64(2330), h.UniqueTreeSize, "unique tree size")
+		assert.Equal(t, counts.Count64(80), h.UniqueTreeEntries, "unique tree entries")
+		assert.Equal(t, counts.Count32(10), h.MaxTreeEntries, "max tree entries")
+		assert.Equal(t, "master:d0/d0/d0/d0/d0/d0/d0/d0/d0", h.MaxTreeEntriesTree.BestPath(), "max tree entries tree")
+
+		assert.Equal(t, counts.Count32(1), h.UniqueBlobCount, "unique blob count")
+		assert.Equal(t, counts.Count64(6), h.UniqueBlobSize, "unique blob size")
+		assert.Equal(t, counts.Count32(6), h.MaxBlobSize, "max blob size")
+		assert.Equal(t, "master:d0/d0/d0/d0/d0/d0/d0/d0/d0/f0", h.MaxBlobSizeBlob.BestPath(), "max blob size blob")
+
+		assert.Equal(t, counts.Count32(0), h.UniqueTagCount, "unique tag count")
+		assert.Equal(t, counts.Count32(0), h.MaxTagDepth, "max tag depth")
+
+		assert.Equal(t, counts.Count32(0), h.ReferenceCount, "reference count")
+
+		assert.Equal(t, counts.Count32(8), h.MaxPathDepth, "max path depth")
+		assert.Equal(t, "master:d0/d0", h.MaxPathDepthTree.BestPath(), "max path depth tree")
+		assert.Equal(t, counts.Count32(23), h.MaxPathLength, "max path length")
+		assert.Equal(t, "master:d0/d0", h.MaxPathLengthTree.BestPath(), "max path length tree")
+
+		assert.Equal(t, counts.Count32((pow(10, 8)-1)/(10-1)), h.MaxExpandedTreeCount, "max expanded tree count")
+		assert.Equal(t, "master:d0/d0", h.MaxExpandedTreeCountTree.BestPath(), "max expanded tree count tree")
+		assert.Equal(t, counts.Count32(pow(10, 8)), h.MaxExpandedBlobCount, "max expanded blob count")
+		assert.Equal(t, "master:d0/d0", h.MaxExpandedBlobCountTree.BestPath(), "max expanded blob count tree")
+		assert.Equal(t, counts.Count64(6*pow(10, 8)), h.MaxExpandedBlobSize, "max expanded blob size")
+		assert.Equal(t, "master:d0/d0", h.MaxExpandedBlobSizeTree.BestPath(), "max expanded blob size tree")
+		assert.Equal(t, counts.Count32(0), h.MaxExpandedLinkCount, "max expanded link count")
+		assert.Nil(t, h.MaxExpandedLinkCountTree, "max expanded link count tree")
+		assert.Equal(t, counts.Count32(0), h.MaxExpandedSubmoduleCount, "max expanded submodule count")
+		assert.Nil(t, h.MaxExpandedSubmoduleCountTree, "max expanded submodule count tree")
+	})
 }
 
 func TestTaggedTags(t *testing.T) {
@@ -650,9 +708,14 @@ func TestTaggedTags(t *testing.T) {
 	refRoots, err := sizes.CollectReferences(ctx, repo, refGrouper{})
 	require.NoError(t, err)
 
+	roots := make([]sizes.Root, 0, len(refRoots))
+	for _, refRoot := range refRoots {
+		roots = append(roots, refRoot)
+	}
+
 	h, err := sizes.ScanRepositoryUsingGraph(
 		context.Background(), repo,
-		refRoots, sizes.NameStyleNone, meter.NoProgressMeter,
+		roots, sizes.NameStyleNone, meter.NoProgressMeter,
 	)
 	require.NoError(t, err, "scanning repository")
 	assert.Equal(t, counts.Count32(3), h.MaxTagDepth, "tag depth")
@@ -679,9 +742,14 @@ func TestFromSubdir(t *testing.T) {
 	refRoots, err := sizes.CollectReferences(ctx, repo, refGrouper{})
 	require.NoError(t, err)
 
+	roots := make([]sizes.Root, 0, len(refRoots))
+	for _, refRoot := range refRoots {
+		roots = append(roots, refRoot)
+	}
+
 	h, err := sizes.ScanRepositoryUsingGraph(
 		context.Background(), testRepo.Repository(t),
-		refRoots, sizes.NameStyleNone, meter.NoProgressMeter,
+		roots, sizes.NameStyleNone, meter.NoProgressMeter,
 	)
 	require.NoError(t, err, "scanning repository")
 	assert.Equal(t, counts.Count32(2), h.MaxPathDepth, "max path depth")
@@ -738,10 +806,15 @@ func TestSubmodule(t *testing.T) {
 	mainRefRoots, err := sizes.CollectReferences(ctx, mainRepo, refGrouper{})
 	require.NoError(t, err)
 
+	mainRoots := make([]sizes.Root, 0, len(mainRefRoots))
+	for _, refRoot := range mainRefRoots {
+		mainRoots = append(mainRoots, refRoot)
+	}
+
 	// Analyze the main repo:
 	h, err := sizes.ScanRepositoryUsingGraph(
 		context.Background(), mainTestRepo.Repository(t),
-		mainRefRoots, sizes.NameStyleNone, meter.NoProgressMeter,
+		mainRoots, sizes.NameStyleNone, meter.NoProgressMeter,
 	)
 	require.NoError(t, err, "scanning repository")
 	assert.Equal(t, counts.Count32(2), h.UniqueBlobCount, "unique blob count")
@@ -758,9 +831,14 @@ func TestSubmodule(t *testing.T) {
 	submRefRoots2, err := sizes.CollectReferences(ctx, submRepo2, refGrouper{})
 	require.NoError(t, err)
 
+	submRoots2 := make([]sizes.Root, 0, len(submRefRoots2))
+	for _, refRoot := range submRefRoots2 {
+		submRoots2 = append(submRoots2, refRoot)
+	}
+
 	h, err = sizes.ScanRepositoryUsingGraph(
 		context.Background(), submRepo2,
-		submRefRoots2, sizes.NameStyleNone, meter.NoProgressMeter,
+		submRoots2, sizes.NameStyleNone, meter.NoProgressMeter,
 	)
 	require.NoError(t, err, "scanning repository")
 	assert.Equal(t, counts.Count32(2), h.UniqueBlobCount, "unique blob count")

internal/refopts/ref_group_builder.go

@@ -254,9 +254,14 @@ func (rgb *RefGroupBuilder) AddRefopts(flags *pflag.FlagSet) {
 
 // Finish collects the information gained from processing the options
 // and returns a `sizes.RefGrouper`.
-func (rgb *RefGroupBuilder) Finish() (sizes.RefGrouper, error) {
+func (rgb *RefGroupBuilder) Finish(defaultAll bool) (sizes.RefGrouper, error) {
 	if rgb.topLevelGroup.filter == nil {
-		rgb.topLevelGroup.filter = git.AllReferencesFilter
+		// User didn't specify any reference options.
+		if defaultAll {
+			rgb.topLevelGroup.filter = git.AllReferencesFilter
+		} else {
+			rgb.topLevelGroup.filter = git.NoReferencesFilter
+		}
 	}
 
 	refGrouper := refGrouper{

sizes/explicit_root.go

@@ -0,0 +1,19 @@
+package sizes
+
+import "github.com/github/git-sizer/git"
+
+type ExplicitRoot struct {
+	name string
+	oid  git.OID
+}
+
+func NewExplicitRoot(name string, oid git.OID) ExplicitRoot {
+	return ExplicitRoot{
+		name: name,
+		oid:  oid,
+	}
+}
+
+func (er ExplicitRoot) Name() string { return er.name }
+func (er ExplicitRoot) OID() git.OID { return er.oid }
+func (er ExplicitRoot) Walk() bool   { return true }