What is it?
Your Activity Stream records significant events, like version control changes, in a real-time historical record that lets you search and filter among entries, and correlate entries of different types, as well as providing hyperlinks to commit details, user profiles, project dashboards, and other related data. You can find the Activity Stream display on the Dashboard, as well as the specific pages for projects, services, and user profiles. The latter displays automatically limit response to the ones relevant to that page, but other than that all Activity Stream displays are similar.
If you don’t see the Activity Stream display on your page, ask your administrator to turn on the version control “Users with read access see all commits” feature, or to grant you a role such as Activity Viewer, which includes the “Participation: View Activity” permission.
Wherever you find it, it should look pretty much like this (if you click this image, you should get a larger one in a new window, which might be a useful reference while I explain it). At the top is a search box, but we’ll get back to that in just a moment. The bulk of the display is a list of activities, or events. The entries are listed in reverse-chronological order (most recent first), and wherever possible display terms are hyperlinks to further detail.
- The first line is always some sort of identifier for the activity. In this case, all activities are Git changes, and Git identifies changes with those big, unreadable “hash values” (like “b3640b0fea…”). Other services have other identifiers. But, fortunately, you don’t have to read it: just click it, and you’ll go to the appropriate detail page, with more detailed (and more consumable!) information.
- The next line or so is typically some commentary provided by the author, along with the event being described.
- Following that is information identifying the author (click to see their profile), and the project (click for the project dashboard).
- Entries will often include additional info, such as lists of changed files — it all depends on the individual event.
Now, back to that search box. Actually, you might want to put this blog aside for just a moment, go to your own Dashboard, and play with searches a bit. You should find a lot of it quite obvious and useful, but you may also find a few cases that don’t do what you expected. That’s the time to come back here for explanations!
- Type a word into the search box and hit return. The list will show only entries with that word. For example, if I search for “merge,” I get this. Two things are worth note:
- Not only has the displayed list been shaved down to just the entries mentioning “merge,”
- but there’s also a new label saying so, and a button to “Clear Results” (that is, to return to the original, full list).
Substring search (the wrong way)
- Notice that the second entry (“fix merge damage”) is not actually a merge,it only mentions the word. Let’s restrict the list to actual merges by searching for the sub-string “ranch” (contained in the word “branch”, in all the actual merge events).
- What do we get? Nothing! What’s up with that?
- The problem here is that these searches are word searches, not string searches. While “ranch” is a perfectly fine word, it doesn’t happen to be involved in any of our activities in this project! What we need is a wildcard search: a search for “*ranch”. In general:
- * Means “anything or nothing” (our “*ranch” search would still find the Dude Ranch, if there were one)
- ? Means “exactly one unspecified character”
- Some of these merges go into the branch “master”,some come out. Can we restrict this to just the ones coming out of master? How about searching for “merge branch master”? Whoa! Nope. That’s not right! We get back all kinds of things besides the ones we want!
- The problem here is that what we did was a “multi-word search.” That’s interpreted as “show me every activity that includes any of these words.” This is sometimes useful, like if you should wonder “Was that file named foo? or fu? or fyu?”
- But what we really want here is the phrase ”merge branch master,” not merely “any one of those words.” There’s a way to do that, by quoting the phrase:
- Search for “merge branch master” (with the quotes)
- Now we get the list we wanted
- Notice also that the apostrophes around master (in the results) do not interfere. Again, this is a word-search system; punctuation need not apply.
So, there you have it: a handy, searchable, real-time record of what’s happening in your organization!
How can you put it to work?